docs: add edge CLI command updates (#2703)

* docs: add edge CLI command updates * update edge cli command * fix issues * Apply suggestions from code review Co-authored-by: Yuliia Horbenko <[email protected]> * change api key name * make format * change preposition --------- Co-authored-by: Lenny Chen <[email protected]> Co-authored-by: Yuliia Horbenko <[email protected]>
spectrocloud · May 8, 2024 · 0ba6c55 · 0ba6c55
1 parent 967000a
commit 0ba6c55
Show file tree

Hide file tree

Showing 3 changed files with 177 additions and 54 deletions.
diff --git a/docs/docs-content/clusters/edge/edgeforge-workflow/build-content-bundle.md b/docs/docs-content/clusters/edge/edgeforge-workflow/build-content-bundle.md
@@ -74,8 +74,6 @@ Creating a content bundle provides several benefits that may address common use
 7. You can find the cluster profile ID by reviewing the URL of the current page. The cluster profile ID is the last
    value in the URL. Repeat this step for all the cluster profiles you want to specify in the content bundle.
 
-   <br />
-
    ```text
    https://console.spectrocloud.com/projects/yourProjectId/profiles/cluster/<YourClusterProfileHere>
    ```
@@ -204,6 +202,8 @@ Creating a content bundle provides several benefits that may address common use
 
    </Tabs>
 
+   After creating the file, use the `-cred-file-path filepath` flag to include the credentials in the command.
+
 9. Navigate back to your terminal window and issue the following command to create the content bundle. Replace the
    placeholder values with your actual values.
 
@@ -219,40 +219,29 @@ Creating a content bundle provides several benefits that may address common use
     --project-id <PROJECT_ID> \
     --cluster-profile-ids <CLUSTER_PROFILE_ID1,CLUSTER_PROFILE_ID2...> \
     --palette-endpoint <Palette API Endpoint> \
-    --outfile <bundle-name>.tar \
+    --outfile <bundle-name> \
+    --cred-file-path <file-path> \
     --include-palette-content \
-    --iso
    ```
 
-   ```hideClipboard shell
-   # Output
-   INFO[0000] getting hubble export for build
-   INFO[0000] Fetching latest version for service 'stylus'
-   INFO[0000] stylus version: 3.4.3
-   INFO[0000] Fetching manifest for service stylus and version 3.4.3 for action resources
-   INFO[0000] Fetching manifest of service stylus and version '3.4.3' for action resources
-   INFO[0000] Fetching manifest from service stylus and version '3.4.3' for action resources with file name images.yaml
-   INFO[0000] Get manifest with file name: images.yaml
-   INFO[0000] Get manifest with file content: image: gcr.io/spectro-images-public/stylus:v3.4.3
-   INFO[0002] successfully pulled image : gcr.io/spectro-images-public/calico/cni:v3.25.0
-   ...
-   ...
-   INFO[0143] Total translation table size: 0
-   INFO[0143] Total rockridge attributes bytes: 272
-   INFO[0143] Total directory bytes: 0
-   INFO[0143] Path table size(bytes): 10
-   INFO[0143] Max brk space used 0
-   INFO[0143] 872027 extents written (1703 MB)
-   INFO[0144] ISO file created successfully
-   ```
-
-The result is a content bundle that you can use to preload into your installer. For more information, refer to
-[Build Edge Artifacts with Content Bundle](./palette-canvos/build-artifacts.md) or
-[Build Installer ISO](./palette-canvos/build-installer-iso.md). Our Tech Preview feature
-[local UI](../local-ui/local-ui.md) also allows you to upload content bundles to a disconnected Edge deployment.
-
-Alternatively, you can use the ISO version of the content bundle and transfer it to a USB drive to be used separately at
-the time of Edge host installation.
+   | Flag                        | Description                                                                                                             |
+   | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+   | `--api-key`                 | Your Palette API key.                                                                                                   |
+   | `--cluster-profile-ids`     | Comma-separated list of cluster profile IDs to download content for.                                                    |
+   | `--cred-file-path`          | Path to the JSON file storing registry credentials if you are using a private registry.                                 |
+   | `--include-palette-content` | Whether to include content necessary for Palette itself. Required for airgap installations.                             |
+   | `--outfile`                 | Name of your content bundle. The final file name should have the following pattern: `core-<bundle-name>-random-string`. |
+   | `--palette-endpoint`        | API endpoint for your Palette instance.                                                                                 |
+   | `--project-id`              | The ID of your Palette project.                                                                                         |
+
+   The result is a content bundle that you can use to preload into your installer. For more information, refer to
+   [Build Edge Artifacts with Content Bundle](./palette-canvos/build-artifacts.md) or
+   [Build Installer ISO](./palette-canvos/build-installer-iso.md). Our Tech Preview feature
+   [local UI](../local-ui/local-ui.md) also allows you to upload content bundles to a disconnected Edge deployment.
+
+   Alternatively, you can use the ISO version of the content bundle and transfer it to a USB drive to be used separately
+   at the time of Edge host installation using the `-iso` flag in your build command. Doing so will override the file
+   extension you provide using the `--outfile` flag.
 
 ## Validate
 

diff --git a/...docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-artifacts.md b/...docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-artifacts.md
@@ -62,8 +62,8 @@ To complete this guide, you will need the following items:
 - You must have completed the [Build Edge Artifacts](palette-canvos.md) guide to build the provider images and create a
   cluster profile referencing one of the provider images.
 
-- A Spectro Cloud API key. Later in this guide, you will use this API key to authenticate the Palette Edge CLI utility
-  and allow it to interact with Palette. Refer to the
+- A Palette API key. Later in this guide, you will use this API key to authenticate the Palette Edge CLI utility and
+  allow it to interact with Palette. Refer to the
   [User Authentication](/docs/docs-content/user-management/authentication/api-key/create-api-key.md) guide to create a
   new API key.
 
@@ -166,15 +166,142 @@ Use the following instructions on your Linux machine, which this guide refers to
     export PROFILE_ID=[USE-YOUR-PROFILE-ID_HERE]
     ```
 
-14. Issue the command below to create the content bundle. The `build` command uses the following flags:
+14. (Optional) If your cluster profile uses images or helm charts that are hosted on private registries that require
+    authentication, you must provide a JSON file that contains the necessary credentials to access the registry.
 
-    | **Command Flag**        | **Value**                                                                                                                                           |
-    | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-    | `--api-key`             | Spectro Cloud API key                                                                                                                               |
-    | `--project-id`          | Palette project ID                                                                                                                                  |
-    | `--cluster-profile-ids` | Cluster profile IDs. If you want to include multiple cluster profiles in the content bundle, add multiple cluster profile IDs separated by a comma. |
-    | `--palette-endpoint`    | Palette API endpoint. The default Palette API endpoint is `api.spectrocloud.com`                                                                    |
-    | `--outfile`             | Path to write the final content bundle.                                                                                                             |
+    <Tabs>
+
+    <TabItem value="helm" label="Helm">
+
+    For authenticated access to Helm charts, your must provide credentials with the following schema. Use a key at the
+    root level of the JSON object named "helm" and set its value to a list. The list is a list of credentials for each
+    Helm chart repository. For each set of credentials, use an object in the list with the keys `endpoint`, `username`,
+    and `password`.
+
+    ```json
+    {
+      "helm": [
+          {
+            "endpoint": <Registry URL>,
+            "username": <Registry username>,
+            "password": <Password>
+          }
+      ]
+    }
+    ```
+
+    For example, the following JSON code is a valid set of credentials.
+
+    ```json
+    {
+      "helm": [
+        {
+          "endpoint": "harbor.abcd.com",
+          "username": "admin",
+          "password": "xxxxxxxx"
+        }
+      ]
+    }
+    ```
+
+    </TabItem>
+
+    <TabItem value="image" label="Image">
+
+    For image registries, you must provide credentials with the following schema. Provide a key at the root level of the
+    JSON object named "image" and set its value to a list. The list is a list of credentials for each Helm chart
+    repository. For each set of credentials, use an object in the list with the keys `endpoint`, `username`, and
+    `password`.
+
+    ```json
+    {
+      "image": [
+          {
+            "endpoint": <Registry URL>,
+            "username": <Registry username>,
+            "password": <Password>
+          }
+      ]
+    }
+    ```
+
+    For example, the following JSON code provides access to two registries `ttl.sh` and `docker.io` with two
+    username-password pairs.
+
+    ```json
+    {
+      "image": [
+        {
+          "endpoint": "ttl.sh",
+          "username": "admin",
+          "password": "Welc0me!123"
+        },
+        {
+          "endpoint": "docker.io",
+          "username": "akhileshpvt",
+          "password": "Lucent122333!"
+        }
+      ]
+    }
+    ```
+
+    For Google Container Registry (GCR) access, you need to set the username field to `"_json_key"` and set the password
+    to a JSON object containing the following fields.
+
+    | Field                         | Description                                                                                         |
+    | ----------------------------- | --------------------------------------------------------------------------------------------------- |
+    | `type`                        | The type of credential, which is `service_account` for Google Cloud service accounts.               |
+    | `project_id`                  | The project ID associated with your Google Cloud project. For example, `spectro-images`.            |
+    | `private_key_id`              | A unique identifier for the private key associated with the service account.                        |
+    | `private_key`                 | The private key that is used to authenticate to Google Cloud services, encapsulated in a PEM block. |
+    | `client_email`                | The email address associated with the service account, used for authentication.                     |
+    | `client_id`                   | The client ID associated with the service account.                                                  |
+    | `auth_uri`                    | The URI for the authentication provider, typically Google's OAuth 2.0 server.                       |
+    | `token_uri`                   | The URI for obtaining tokens from Google's OAuth 2.0 server.                                        |
+    | `auth_provider_x509_cert_url` | The URL of the public x509 certificate for the authentication provider.                             |
+    | `client_x509_cert_url`        | The URL of the public x509 certificate for the client (service account).                            |
+
+    For example, the following is a valid set of credentials for a GCR registry.
+
+    ```json
+    {
+      "image": [
+        {
+          "endpoint": "gcr.io",
+          "username": "_json_key",
+          "password": {
+            "type": "service_account",
+            "project_id": "spectro-images",
+            "private_key_id": "847c09190xxxxxxxxxxxxc4ebc",
+            "private_key": "-----BEGIN KEY-----MIIEvQIBADA ... -----Shortened for brevity",
+            "client_email": "xxx.iam.gserviceaccount.com",
+            "client_id": "115830xxxxxxx340453",
+            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+            "token_uri": "https://oauth2.googleapis.com/token",
+            "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+            "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/spectro-images-viewer%40spectro-images.iam.gserviceaccount.com"
+          }
+        }
+      ]
+    }
+    ```
+
+    </TabItem>
+
+    </Tabs>
+
+    After creating the file, use the `--cred-file-path filepath` flag to include the credentials in the command.
+
+15. Issue the command below to create the content bundle. The `build` command uses the following flags:
+
+    | **Command Flag**        | **Value**                                                                                                                                          |
+    | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+    | `--api-key`             | Palette API key.                                                                                                                                   |
+    | `--project-id`          | Palette project ID.                                                                                                                                |
+    | `--cluster-profile-ids` | Cluster profile IDs. If you want to include multiple cluster profiles in the content bundle, add multiple cluster profile IDs separated by commas. |
+    | `--palette-endpoint`    | Palette API endpoint. The default Palette API endpoint is `api.spectrocloud.com`.                                                                  |
+    | `--outfile`             | Name of the content bundle. The final filename looks like the following: `core-<bundle-name>-random-string`.                                       |
+    | `--cred-file-path`      | Path to the JSON file containing the credentials for a private registry.                                                                           |
 
     You can issue `palette-edge build --help` to know about other available flags.
 
@@ -183,18 +310,20 @@ Use the following instructions on your Linux machine, which this guide refers to
     --project-id $PROJECT_ID \
     --cluster-profile-ids $PROFILE_ID \
     --palette-endpoint api.spectrocloud.com \
-    --outfile content
+    --outfile <bundle-name> \
+    --include-palette-content \
+    --cred-file-path filepath
     ```
 
-15. Use the command below to list all files in the current directory to verify that you created the content bundle
+16. Use the following command to list all files in the current directory to verify that you created the content bundle
     successfully. The content bundle will have the following naming convention, `content-[random-string]`, for example,
     **content-8e61a9e5**.
 
     ```bash
     ls -al
     ```
 
-16. List the files in the content bundle folder using the following command. The output will display the compressed core
+17. List the files in the content bundle folder using the following command. The output will display the compressed core
     and app content files.
 
     ```bash
@@ -204,13 +333,12 @@ Use the following instructions on your Linux machine, which this guide refers to
     ```hideClipboard bash
     # Sample output
     total 3981104
-    -rw-rw-r-- 1 jb jb 1598552722 Jul 26 18:20 app-content-8e61a9e5.zst
     -rw-rw-r-- 1 jb jb 2478086360 Jul 26 18:20 core-content-8e61a9e5.zst
     ```
 
-17. Issue the following command to build the Edge artifacts with your content bundle. The `+iso` option specifies the
-    build target. This command will generate an ISO image from the content bundle and other configurations you have
-    specified in the **.arg** and **user-data** files.
+18. Issue the following command to build the Edge artifacts with your content bundle. The `+iso` option specifies the
+    build target. This command will generate an ISO image containing the content bundle and other configurations you
+    have specified in the **.arg** and **user-data** files.
 
     ```bash
     sudo ./earthly.sh +iso

diff --git a/...ters/edge/site-deployment/deploy-custom-registries/upload-images-to-registry.md b/...ters/edge/site-deployment/deploy-custom-registries/upload-images-to-registry.md
@@ -177,19 +177,25 @@ download the images and upload them to the external registry.
 
 8. Issue the following command to download the images as a content bundle. The command produces a ZST file as output.
    Replace the `******` after the `--api-key` flag with your Palette API key. Replace `project-ID` with the ID of your
-   project in Palette, and `profile-ID` with the ID of your profile.
+   project in Palette, `palette-api-endpoint` with your Palette API endpoint, and `profile-ID` with the ID of your
+   profile.
 
    ```shell
-    ./palette-edge build --api-key ****** --project-id project-ID --cluster-profile-ids profile-ID \
-        --outfile output-file-name --cred-file-path registry-creds.json --include-palette-content
+    ./palette-edge build --api-key ****** \
+    --project-id project-ID \
+    --cluster-profile-ids profile-ID \
+    --palette-endpoint palette-API-endpoint \
+    --outfile output-file-name \
+    --cred-file-path registry-creds.json \
+    --include-palette-content
    ```
 
 9. Issue the following command to upload the images to the external registry. Replace `path-to-content-bundle` with the
    path to the content bundle you downloaded in the previous step. Replace `registry-URL` with the URL of your external
    registry. Replace `username` and `******` with the username and password used to access the external registry.
 
    ```shell
-   ./palette-edge-cli deploy --export path-to-content-bundle --registry registry-URL \
+   ./palette-edge deploy --export path-to-content-bundle --url registry-URL \
     --username username --password ******
    ```