From d531907c68883c2cc2d2bd00957fcd5b9ae503d9 Mon Sep 17 00:00:00 2001 From: caroldelwing Date: Tue, 17 Sep 2024 16:26:46 -0400 Subject: [PATCH 1/3] docs: document api breaking change/known issue (#3951) * docs: document api breaking change/known issue * docs: address review suggestions --- docs/docs-content/release-notes/known-issues.md | 1 + docs/docs-content/release-notes/release-notes.md | 11 +++++++---- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/docs-content/release-notes/known-issues.md b/docs/docs-content/release-notes/known-issues.md index bf03d2ede0..d7cbf6cd4b 100644 --- a/docs/docs-content/release-notes/known-issues.md +++ b/docs/docs-content/release-notes/known-issues.md @@ -16,6 +16,7 @@ The following table lists all known issues that are currently active and affecti | Description | Workaround | Publish Date | Product Component | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------- | +| A change in the [Edge Native Cluster](https://docs.spectrocloud.com/api/v1/v-1-spectro-clusters-edge-native-create/) API endpoint affects Terraform and API workflows for Edge cluster creation or modification. The `type` parameter in the `controlPlaneEndpoint` no longer accepts IP addresses; the accepted values are now `VIP`, `External`, and `DDNS`. As a result, API and Terraform workflows for Edge cluster creation or modification that use the IP address are currently unavailable. | For the Terraform workflow, upgrade the Terraform provider to version `0.21.4`. This new version supports the use of IP addresses and sends the `VIP` value to the API. No workaround is available for the API workflow. | September 17, 2024 | Edge | | If an Edge host operating a cluster in connected mode loses connection to Palette, the cluster will not auto-renew its Public Key Infrastructure (PKI) certificates. When it re-establishes the connection to Palette, the Edge host will renew the certificates if the existing certificates have less than 30 days before expiry. | No workaround available. | Sep 14, 2024 | Edge | | Using the Flannel Container Network Interface (CSI) pack together with a Red Hat Enterprise Linux (RHEL)-based provider image may lead to a pod becoming stuck during deployment. This is caused by an upstream issue with Flannel that was discovered in a K3s GitHub issue. Refer to [the K3s issue page](https://github.com/k3s-io/k3s/issues/5013) for more information. | No workaround is available | Sep 14, 2024 | Edge | | Palette OVA import operations fail if the VMO cluster is using a storageClass with the volume bind method `WaitForFirstConsumer`. | Refer to the [OVA Imports Fail Due To Storage Class Attribute](../troubleshooting/vmo-issues.md#scenario---ova-imports-fail-due-to-storage-class-attribute) troubleshooting guide for workaround steps. | September 13, 2024 | Palette CLI, VMO | diff --git a/docs/docs-content/release-notes/release-notes.md b/docs/docs-content/release-notes/release-notes.md index 98fcfc717f..a27120bbd1 100644 --- a/docs/docs-content/release-notes/release-notes.md +++ b/docs/docs-content/release-notes/release-notes.md @@ -61,10 +61,6 @@ tags: ["release-notes"] to the [Edge Installer User Data Configuration](../clusters/edge/edge-configuration/edge-configuration.md) reference page for more information. -- A change in the Palette API affects Edge clusters deployed with Terraform or the Palette API. The `type` parameter in - the `controlPlaneEndpoint` for Edge clusters no longer accepts IP addresses. The accepted values are now `VIP`, - `External`, and `DDNS`. - #### Features - You can now configure the Maximum Transmission Unit (MTU) for network interface configured for discovery though @@ -86,6 +82,13 @@ tags: ["release-notes"] (TUI) to enhance the user experience. These improvements include more visible options menus, automatic configuration save upon exit, improved color scheme, and more. +#### Known Issues + +- A change in the [Edge Native Cluster](https://docs.spectrocloud.com/api/v1/v-1-spectro-clusters-edge-native-create/) + API endpoint affects Terraform and API workflows for Edge cluster creation or modification. The `type` parameter in + the `controlPlaneEndpoint` no longer accepts IP addresses. The accepted values are now `VIP`, `External`, and `DDNS`. + Refer to the [Known Issues](./known-issues.md) page for more information. + ### Virtual Machine Orchestrator #### Features From 74434c5557fffa2bb4ba307a977d18b0fb9470a1 Mon Sep 17 00:00:00 2001 From: Lenny Chen <55669665+lennessyy@users.noreply.github.com> Date: Tue, 17 Sep 2024 14:15:01 -0700 Subject: [PATCH 2/3] docs: add instruction about json file for k8s versions (#3936) * docs: add instruction about json versions * docs: capitalization * docs: typo --------- Co-authored-by: Lenny Chen --- .../palette-canvos/build-provider-images.md | 16 +++++--- .../edgeforge-workflow/palette-canvos/fips.md | 10 +++-- .../palette-canvos/palette-canvos.md | 40 +++++++++---------- .../edgeforge/build-trusted-provider-image.md | 14 ++++--- 4 files changed, 46 insertions(+), 34 deletions(-) diff --git a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-provider-images.md b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-provider-images.md index ff362ff469..e3bea22797 100644 --- a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-provider-images.md +++ b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-provider-images.md @@ -65,10 +65,10 @@ artifacts at the same time. git tag ``` -4. Check out the newest available tag. This guide uses the tag **v4.3.0** as an example. +4. Check out the newest available tag. This guide uses the tag **v4.4.12** as an example. ```shell - git checkout v4.3.0 + git checkout v4.4.12 ``` 5. Review the files relevant for this guide. @@ -102,8 +102,12 @@ artifacts at the same time. export OS_VERSION=22.04 ``` -9. Open the **Earthfile** in the CanvOS directory. Under `build-provider-images`, remove the lines containing Kubernetes - versions that you do not need. +9. Open the **k8s_versions.json** file in the CanvOS directory. Remove the Kubernetes versions that you don't need from + the JSON object corresponding to your Kubernetes distribution. + + If you are using a tag that is earlier than v4.4.12, the **k8s_versions.json** file does not exist in those tags. + Instead, open the **Earthfile** in the CanvOS directory. Under `build-provider-images`, remove the lines containing + Kubernetes versions that you do not need. 10. Issue the command below to create an **.arg** file. The **.arg** file uses the default values for the remaining arguments. @@ -155,7 +159,7 @@ artifacts at the same time. `[REGISTRY-HOSTNAME]` and version numbers in the command below. ```bash - docker push [REGISTRY-HOSTNAME]/ubuntu:k3s-1.28.2-v4.3.0-palette-learn + docker push [REGISTRY-HOSTNAME]/ubuntu:k3s-1.28.2-v4.4.12-palette-learn ``` ## Validate @@ -171,7 +175,7 @@ artifacts at the same time. ```hideClipboard REPOSITORY TAG IMAGE ID CREATED SIZE - docker.io/[DOCKER-ID]/ubuntu k3s-1.28.2-v4.3.0-palette-learn 075134ad5d4b 10 minutes ago 4.11GB + docker.io/[DOCKER-ID]/ubuntu k3s-1.28.2-v4.4.12-palette-learn 075134ad5d4b 10 minutes ago 4.11GB ``` ## Next Steps diff --git a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/fips.md b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/fips.md index 2075c80f19..6e1c826a9e 100644 --- a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/fips.md +++ b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/fips.md @@ -84,11 +84,11 @@ Palette is not FIPS compliant. If you need a FIPS-compliant solution, you need t ``` 3. View the available tags and check out the latest tag or any specific version of your choosing. This guide uses - **v4.3.2** as an example. + **v4.4.12** as an example. ```bash git tag - git checkout v4.3.2 + git checkout v4.4.12 ``` ### Build FIPS-Compliant Base OS Image @@ -266,7 +266,11 @@ workaround. Provider images are Kairos-based container images for a supported OS and Kubernetes distribution combination. FIPS-complaint provider images are built on top of the base OS image you have built previously. -17. Locate **Earthfile** in the CanvOS directory. In the file, find the block that starts with +17. Open the **k8s_versions.json** file in the CanvOS directory. Remove the Kubernetes versions that you don't need from + the JSON object corresponding to your Kubernetes distribution. + + If you are using a tag that is earlier than v4.4.12, the **k8s_versions.json** file does not exist in those tags. + Instead, open the **Earthfile** in the CanvOS directory. In the file, find the block that starts with `build-provider-images-fips:` and delete the Kubernetes versions that you do not want. This will speed up the build process and save storage space. diff --git a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/palette-canvos.md b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/palette-canvos.md index 50953775f2..f0ba60d2f1 100644 --- a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/palette-canvos.md +++ b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/palette-canvos.md @@ -114,10 +114,10 @@ customization. git tag ``` -4. Check out the newest available tag. This guide uses the tag **v4.0.6** as an example. +4. Check out the newest available tag. This guide uses the tag **v4.4.12** as an example. ```shell - git checkout v4.0.6 + git checkout v4.4.12 ``` 5. Review the files relevant for this guide. @@ -152,7 +152,7 @@ customization. Using the arguments defined in the **.arg** file, the final provider images you generate will have the following naming convention, `[IMAGE_REGISTRY]/[IMAGE_REPO]:[CUSTOM_TAG]`. For example, one of the provider images will be - `ttl.sh/ubuntu:k3s-1.27.2-v4.0.6-palette-learn`. + `ttl.sh/ubuntu:k3s-1.27.2-v4.4.12-palette-learn`. ```bash cat << EOF > .arg @@ -279,7 +279,7 @@ customization. system.repo: ubuntu system.k8sDistribution: k3s system.osName: ubuntu - system.peVersion: v4.0.6 + system.peVersion: v4.4.12 system.customTag: palette-learn system.osVersion: 22 ``` @@ -294,9 +294,9 @@ customization. ```hideClipboard bash REPOSITORY TAG IMAGE ID CREATED SIZE - ttl.sh/ubuntu k3s-1.27.2-v4.0.6-palette-learn 075134ad5d4b 10 minutes ago 4.11GB - ttl.sh/ubuntu k3s-1.25.2-v4.0.6-palette-learn 02424d29fcac 10 minutes ago 4.09GB - ttl.sh/ubuntu k3s-1.26.4-v4.0.6-palette-learn 4e373ddfb53f 10 minutes ago 4.11GB + ttl.sh/ubuntu k3s-1.27.2-v4.4.12-palette-learn 075134ad5d4b 10 minutes ago 4.11GB + ttl.sh/ubuntu k3s-1.25.2-v4.4.12-palette-learn 02424d29fcac 10 minutes ago 4.09GB + ttl.sh/ubuntu k3s-1.26.4-v4.4.12-palette-learn 4e373ddfb53f 10 minutes ago 4.11GB ``` 13. To use the provider images in your cluster profile, push them to the image registry mentioned in the **.arg** file. @@ -305,9 +305,9 @@ customization. following commands to push the provider images to the _ttl.sh_ image registry. ```bash - docker push ttl.sh/ubuntu:k3s-1.25.2-v4.0.6-palette-learn - docker push ttl.sh/ubuntu:k3s-1.26.4-v4.0.6-palette-learn - docker push ttl.sh/ubuntu:k3s-1.27.2-v4.0.6-palette-learn + docker push ttl.sh/ubuntu:k3s-1.25.2-v4.4.12-palette-learn + docker push ttl.sh/ubuntu:k3s-1.26.4-v4.4.12-palette-learn + docker push ttl.sh/ubuntu:k3s-1.27.2-v4.4.12-palette-learn ``` :::warning @@ -366,7 +366,7 @@ customization. system.repo: ubuntu system.k8sDistribution: k3s system.osName: ubuntu - system.peVersion: v4.0.6 + system.peVersion: v4.4.12 system.customTag: palette-learn system.osVersion: 22 ``` @@ -495,7 +495,7 @@ git tag 4. Check out the newest available tag. This guide uses **v3.4.3** tag as an example. ```shell -git checkout v4.0.6 +git checkout v4.4.12 ``` 5. Review the files relevant for this guide. @@ -740,7 +740,7 @@ git checkout v4.0.6 system.repo: opensuse-leap system.k8sDistribution: k3s system.osName: opensuse-leap - system.peVersion: v4.0.6 + system.peVersion: v4.4.12 system.customTag: palette-learn system.osVersion: ``` @@ -755,9 +755,9 @@ git checkout v4.0.6 ```hideClipboard bash REPOSITORY TAG IMAGE ID CREATED SIZE - spectrocloud/opensuse-leap k3s-1.27.2-v4.0.6-palette-learn 2427e3667b2f 24 minutes ago 2.22GB - spectrocloud/opensuse-leap k3s-1.26.6-v4.0.6-palette-learn 0f2efd533a33 24 minutes ago 2.22GB - spectrocloud/opensuse-leap k3s-1.25.2-v4.0.6-palette-learn 2427e3667b2f 24 minutes ago 2.22GB + spectrocloud/opensuse-leap k3s-1.27.2-v4.4.12-palette-learn 2427e3667b2f 24 minutes ago 2.22GB + spectrocloud/opensuse-leap k3s-1.26.6-v4.4.12-palette-learn 0f2efd533a33 24 minutes ago 2.22GB + spectrocloud/opensuse-leap k3s-1.25.2-v4.4.12-palette-learn 2427e3667b2f 24 minutes ago 2.22GB ``` 16. To use the provider images in your cluster profile, push them to your image registry mentioned in the **.arg** file. @@ -776,9 +776,9 @@ git checkout v4.0.6 the utility created. ```bash - docker push docker.io/[DOCKER-ID]/opensuse-leap:k3s-1.27.2-v4.0.6-palette-learn - docker push docker.io/[DOCKER-ID]/opensuse-leap:k3s-1.26.6-v4.0.6-palette-learn - docker push docker.io/[DOCKER-ID]/opensuse-leap:k3s-1.25.2-v4.0.6-palette-learn + docker push docker.io/[DOCKER-ID]/opensuse-leap:k3s-1.27.2-v4.4.12-palette-learn + docker push docker.io/[DOCKER-ID]/opensuse-leap:k3s-1.26.6-v4.4.12-palette-learn + docker push docker.io/[DOCKER-ID]/opensuse-leap:k3s-1.25.2-v4.4.12-palette-learn ``` 18. After pushing the provider images to the image registry, open a web browser and log in to @@ -828,7 +828,7 @@ git checkout v4.0.6 system.repo: opensuse-leap system.k8sDistribution: k3s system.osName: opensuse-leap - system.peVersion: v4.0.6 + system.peVersion: v4.4.12 system.customTag: palette-learn system.osVersion: ``` diff --git a/docs/docs-content/clusters/edge/trusted-boot/edgeforge/build-trusted-provider-image.md b/docs/docs-content/clusters/edge/trusted-boot/edgeforge/build-trusted-provider-image.md index 21f7507b15..39f0ae0829 100644 --- a/docs/docs-content/clusters/edge/trusted-boot/edgeforge/build-trusted-provider-image.md +++ b/docs/docs-content/clusters/edge/trusted-boot/edgeforge/build-trusted-provider-image.md @@ -69,10 +69,10 @@ key that is in the Signature Database (DB). This is important both during instal git tag ``` -4. Check out the newest available tag. This guide uses the tag **v4.4.0** as an example. +4. Check out the newest available tag. This guide uses the tag **v4.4.12** as an example. ```shell - git checkout v4.4.0 + git checkout v4.4.12 ``` 5. Review the files relevant for this guide. @@ -135,7 +135,11 @@ key that is in the Signature Database (DB). This is important both during instal | `OS_DISTRIBUTION` | OS distribution. | `ubuntu`, `opensuse-leap`, `rhel`. | | `OS_VERSION` | OS version. This applies to Ubuntu only. | `23.10`, `24.04` | -10. Open the **Earthfile** in the CanvOS directory. Under `build-provider-images`, remove the lines containing +10. Open the **k8s_versions.json** file in the CanvOS directory. Remove the Kubernetes versions that you don't need from + the JSON object corresponding to your Kubernetes distribution. + + If you are using a tag that is earlier than v4.4.12, the **k8s_versions.json** file does not exist in those tags. + Instead, open the **Earthfile** in the CanvOS directory. Under `build-provider-images`, remove the lines containing Kubernetes versions that you do not need. 11. CanvOS utility uses [Earthly](https://earthly.dev/) to build the target artifacts. Issue the following command to @@ -162,7 +166,7 @@ key that is in the Signature Database (DB). This is important both during instal `[DOCKER-ID]` and version numbers in the command below with your Docker ID and respective Kubernetes versions. ```bash - docker push docker.io/[DOCKER-ID]/ubuntu:rke2-1.28.2-v4.4.0-trusted-boot + docker push docker.io/[DOCKER-ID]/ubuntu:rke2-1.28.2-v4.4.12-trusted-boot ``` ## Validate @@ -178,5 +182,5 @@ key that is in the Signature Database (DB). This is important both during instal ```hideClipboard REPOSITORY TAG IMAGE ID CREATED SIZE - docker.io/[DOCKER-ID]/ubuntu rke2-1.28.2-v4.4.0-trusted-boot 075134ad5d4b 10 minutes ago 1.79GB + docker.io/[DOCKER-ID]/ubuntu rke2-1.28.2-v4.4.12-trusted-boot 075134ad5d4b 10 minutes ago 1.79GB ``` From 8c9cbab4d0c13cc3e761b9b5fad9af7d151d016c Mon Sep 17 00:00:00 2001 From: Karl Cardenas <29551334+karl-cardenas-coding@users.noreply.github.com> Date: Tue, 17 Sep 2024 14:35:50 -0700 Subject: [PATCH 3/3] docs: DOC-1362 (#3929) * docs: DOC-1362 * docs: more updates * docs: vale fix * docs: feedback apply suggestions from code review Co-authored-by: caroldelwing * ci: auto-formatting prettier issues * docs: feedback * docs: feedback changes --------- Co-authored-by: caroldelwing Co-authored-by: karl-cardenas-coding --- .../automation/palette-sdk/palette-sdk.md | 4 + .../authentication/api-key/api-key.md | 37 ++ .../authentication/api-key/delete-api-key.md | 324 +++++++++++++++++- .../user-management/saml-sso/saml-sso.md | 16 + 4 files changed, 378 insertions(+), 3 deletions(-) diff --git a/docs/docs-content/automation/palette-sdk/palette-sdk.md b/docs/docs-content/automation/palette-sdk/palette-sdk.md index 72530b07e6..3a94e7eed2 100644 --- a/docs/docs-content/automation/palette-sdk/palette-sdk.md +++ b/docs/docs-content/automation/palette-sdk/palette-sdk.md @@ -23,6 +23,10 @@ The snippet below showcases an example of how to initialize the Palette client u methods. ```go + import ( + "github.com/spectrocloud/palette-sdk-go/client" + ) + pc := client.New( client.WithPaletteURI(host), client.WithAPIKey(apiKey), diff --git a/docs/docs-content/user-management/authentication/api-key/api-key.md b/docs/docs-content/user-management/authentication/api-key/api-key.md index c7703f9472..090a3eaf94 100644 --- a/docs/docs-content/user-management/authentication/api-key/api-key.md +++ b/docs/docs-content/user-management/authentication/api-key/api-key.md @@ -17,6 +17,43 @@ revoke, and delete API keys for any user within the tenant. Each of these action following resources. Refer to the [Tenant Admin API Key Management](../../../tenant-settings/api-key-management.md) section for more information. +## Permissions + +API keys are associated with the user who creates them. The permissions associated with the API key are the same as +those of the user who created the key. If the user has the necessary permissions to perform an action, then the user's +API key can be used to perform the same action programmatically. + +The API key permissions automatically reflect any changes to the user's permissions. If the user belongs to an OIDC/SAML +group, any changes to the external user's group membership are reflected the next time the user logs in. + +## Limitations + +Palette API keys that belong to Palette users removed from the organization through OIDC/SAML are not automatically +removed. We recommend that you remove these keys to ensure that they are no longer used. You can programmatically remove +the API keys using the REST API or the Palette SDK. Check out the [Delete API Key](./delete-api-key.md) page for more +information on how to delete an API key programmatically. + +:::tip + +Tenant administrators can view all API keys created for the tenant. Users are limited to actions for their own API keys. +To learn more about the API key management tasks you can perform as a tenant administrator, refer to the +[Tenant API Key Management](../../../tenant-settings/api-key-management.md) page. + +::: + +## Best Practices + +The following are best practices we recommend for managing Palette API keys: + +- Set an expiration date for API keys to ensure that they are not used indefinitely. Preferably, set the expiration date + to a short duration, such as 30 days, and renew the key as needed. + +- Store API keys securely. Do not expose API keys in public repositories or share them with unauthorized users. Use + secure storage mechanisms, such as a password manager, to store API keys. + +- Regularly review and audit API keys to ensure that they are still required. Remove any API keys that are no longer + needed. + ## Resources - [Tenant Admin API Key Management](../../../tenant-settings/api-key-management.md) diff --git a/docs/docs-content/user-management/authentication/api-key/delete-api-key.md b/docs/docs-content/user-management/authentication/api-key/delete-api-key.md index 803ed68639..14b477de6c 100644 --- a/docs/docs-content/user-management/authentication/api-key/delete-api-key.md +++ b/docs/docs-content/user-management/authentication/api-key/delete-api-key.md @@ -11,10 +11,14 @@ tags: ["user-management", "authentication", "api-key"] You can delete an API key from Palette. A tenant admin can also delete an API key created by another user within the tenant. Use the following steps to delete an API key. +The following sections provide information on how to delete an API key in Palette through the UI, API, and SDK. + +## UI + Tenant administrators can delete an API key on behalf of any user within the tenant. Select the Tenant tab below to learn more about deleting an API key as a tenant admin. -## Prerequisites +### Prerequisites @@ -35,7 +39,7 @@ learn more about deleting an API key as a tenant admin. -## Delete API Key +### Delete API Key in Palette UI @@ -66,7 +70,7 @@ learn more about deleting an API key as a tenant admin. -## Validate +### Validate @@ -92,3 +96,317 @@ learn more about deleting an API key as a tenant admin. + +## API + +You can use the Palette API with the `https://api.spectrocloud.com/v1/apiKeys/:uid` +[endpoint](https://docs.spectrocloud.com/api/v1/v-1-api-keys-uid-delete) and the API key's unique identifier to delete +an API key programmatically. + +Use the following steps to learn how to delete an API key. + +### Prerequisites + +- You must have a valid Palette API key. Refer to the [Create API Key](create-api-key.md) section for more information. + +- A terminal or command prompt to execute the `curl` command. Alternatively, you can use a REST client like + [Postman](https://www.postman.com/). + +### Delete API Key with API + +1. Open a terminal or command prompt. + +2. Issue the following command to retrieve your API key's unique identifier. Replace `API_KEY_VALUE` with your API key. + + ```shell + curl --location 'https://api.spectrocloud.com/v1/apiKeys' \ + --header 'Accept: application/json' \ + --header 'apiKey: API_KEY_VALUE' + ``` + + ```json {17} hideClipboard + { + "items": [ + { + "metadata": { + "annotations": { + "description": "", + "ownerUid": "****************", + "permissions": "apiKey.create,apiKey.delete,apiKey.get,apiKey.list,apiKey.update,tag.update", + "scope": "tenant", + "scopeVisibility": "20", + "tenantUid": "*************************" + }, + "creationTimestamp": "2024-09-16T14:46:28.677Z", + "deletionTimestamp": "0001-01-01T00:00:00.000Z", + "lastModifiedTimestamp": "2024-09-16T14:46:29.079Z", + "name": "remove-me-test", + "uid": "66e844c44bab2337f20c7471" + }, + "spec": { + "expiry": "2024-09-23T14:46:28.164Z", + "user": { + "firstName": "example", + "lastName": "example", + "uid": "*****************" + } + }, + "status": { + "isActive": true + } + } + ] + } + ``` + +3. Once you have the API key's unique identifier, issue the following command to delete the API key. Replace `uid` with + the API key's unique identifier. Specify a valid API key in the `ApiKey` header. + + ```shell + curl -L -X DELETE 'https://api.spectrocloud.com/v1/apiKeys/:uid' \ + -H 'ApiKey: ' + ``` + +4. No output is expected if the API key is successfully deleted. + +### Validate + +1. Verify the API key is no longer available in Palette by issuing the following command. Replace `API_KEY_VALUE` with + your API key. + + ```shell + curl --location 'https://api.spectrocloud.com/v1/apiKeys' \ + --header 'Accept: application/json' \ + --header 'apiKey: API_KEY_VALUE' + ``` + +2. The API key should not be listed in the response. If the API key is still available, verify the API key's unique + identifier and reissue the delete command. You can also validate the deletion by checking the Palette UI. + +## SDK + +You can use the [Palette SDK](../../../automation/palette-sdk/palette-sdk.md) to delete an API key programmatically. + +### Prerequisites + +- You must have a valid Palette API key. Refer to the [Create API Key](create-api-key.md) section for more information. + +- [Go version](https://go.dev/doc/install) 1.22 or later. + +- A text editor or an IDE to write and execute the Go code. + +- A valid Palette API key to delete. In this example, the fictional API key named `delete-test-key` is used. + +- An internet connection to download the Palette SDK and its dependencies. + +### Delete API Key With Go SDK + +1. Create a new directory for your Go project and navigate to the directory. + + ```shell + mkdir delete-api-key && cd delete-api-key + ``` + +2. Create a new Go file, for example, **main.go**. + + ```shell + touch main.go + ``` + +3. Initialize the Go module. Use the following command to initialize the Go module. + + ```shell + go mod init example/delete-api-key + ``` + +4. Open the **main.go** file in your text editor or IDE. + +5. Copy and paste the following code snippet into the **main.go** file. Replace the variable `keyName` with the key name + you want to delete. + + ```go {17} + package main + + import ( + "fmt" + "log" + "log/slog" + "os" + + "github.com/spectrocloud/palette-sdk-go/client" + ) + + func main() { + + host := os.Getenv("PALETTE_HOST") // "api.spectrocloud.com" + apiKey := os.Getenv("PALETTE_API_KEY") // "your api key" + + if host == "" || apiKey == "" { + log.Fatal("Please set PALETTE_HOST and PALETTE_API_KEY environment variables") + } + + keyName := "delete-test-key" // "name of the key to delete. Replace as needed" + + pc := client.New( + client.WithPaletteURI(host), + client.WithAPIKey(apiKey), + ) + + keys, err := pc.GetAPIKeys() + if err != nil { + log.Fatal("Error getting API keys: ", err) + } + + for _, key := range keys.Items { + if key.Metadata.Name == keyName { + slog.Info(fmt.Sprintf("API key found. Deleting API key: %s", key.Metadata.Name)) + err := pc.DeleteAPIKey(key.Metadata.UID) + if err != nil { + log.Fatal("Error deleting API key: ", err) + } + slog.Info("API key deleted successfully") + } + + } + } + ``` + +6. Set the environment variables for the Palette host and API key. Replace `api.spectrocloud.com` with your Palette host + URL if you are using a self-hosted Palette or VerteX instance. + + ```shell + export PALETTE_HOST="api.spectrocloud.com" + export PALETTE_API_KEY="your api key" + ``` + +7. Start the Go program. + + ```shell + go get ./... && go run . + ``` + + ```shell + 2024/09/16 08:27:12 INFO API key found. Deleting API key: delete-test-key + 2024/09/16 08:27:12 INFO API key deleted successfully + ``` + +### Validate + +You can validate the deletion by checking the Palette UI or by querying the API with the `GetAPIKeys()` method to list +the API keys again and verifying the API key is no longer available. + +1. Create a function to list the API keys and verify the API key is no longer available. Use the following code snippet + to validate the deletion. + + ```go + // validateKeyIsRemoved checks if the key is removed + // returns true if the key is removed, false otherwise + func validateKeyIsRemoved(keyName string, pc *client.V1Client) (bool, error) { + + keys, err := pc.GetAPIKeys() + if err != nil { + log.Fatal("Error getting API keys: ", err) + } + + for _, key := range keys.Items { + if key.Metadata.Name == keyName { + return false, nil + } + } + + return true, nil + + } + ``` + +2. Replace the entire content of the **main.go** file with the following code snippet to include the validation check. + + ```go + package main + + import ( + "fmt" + "log" + "log/slog" + "os" + + "github.com/spectrocloud/palette-sdk-go/client" + ) + + func main() { + + host := os.Getenv("PALETTE_HOST") // "api.spectrocloud.com" + apiKey := os.Getenv("PALETTE_API_KEY") // "your api key" + + if host == "" || apiKey == "" { + log.Fatal("Please set PALETTE_HOST and PALETTE_API_KEY environment variables") + } + + keyName := "delete-test-key" // "name of the key to delete" + + pc := client.New( + client.WithPaletteURI(host), + client.WithAPIKey(apiKey), + ) + + keys, err := pc.GetAPIKeys() + if err != nil { + log.Fatal("Error getting API keys: ", err) + } + + for _, key := range keys.Items { + if key.Metadata.Name == keyName { + slog.Info(fmt.Sprintf("API key found. Deleting API key: %s", key.Metadata.Name)) + err := pc.DeleteAPIKey(key.Metadata.UID) + if err != nil { + log.Fatal("Error deleting API key: ", err) + } + slog.Info("API key deleted successfully") + } + + } + + ok, err := validateKeyIsRemoved(keyName, pc) + if err != nil { + log.Fatal("Error validating key is removed: ", err) + } + + if !ok { + log.Fatal("API key is not removed") + } + + slog.Info("Validation ensured the key is removed successfully") + + } + + // validateKeyIsRemoved checks if the key is removed + // returns true if the key is removed, false otherwise + func validateKeyIsRemoved(keyName string, pc *client.V1Client) (bool, error) { + + keys, err := pc.GetAPIKeys() + if err != nil { + log.Fatal("Error getting API keys: ", err) + } + + for _, key := range keys.Items { + if key.Metadata.Name == keyName { + return false, nil + } + } + + return true, nil + + } + ``` + +3. Start the Go program. + + ```shell + go get ./... && go run . + ``` + + ```shell + 2024/09/16 08:35:07 INFO Validation ensured the API key is removed successfully + ``` + +4. The output confirms the API key is successfully deleted. diff --git a/docs/docs-content/user-management/saml-sso/saml-sso.md b/docs/docs-content/user-management/saml-sso/saml-sso.md index 3a4fdcb032..f922400fcf 100644 --- a/docs/docs-content/user-management/saml-sso/saml-sso.md +++ b/docs/docs-content/user-management/saml-sso/saml-sso.md @@ -18,6 +18,22 @@ the following protocols for authentication and authorization. [OAuth 2.0](https://www.rfc-editor.org/rfc/rfc6749), a widely used authorization framework. OIDC supports distributed identity providers and supports social login providers such as Google or GitHub. +## Limitations + +Palette [API keys](../authentication/api-key/api-key.md) that belong to Palette users removed from the organization +through OIDC/SAML are not automatically removed. We recommend that you remove these keys to ensure that they are no +longer used. You can programmatically remove the API keys using the REST API or the Palette SDK. Check out the +[Delete API Key](../authentication/api-key/delete-api-key.md) page for more information on how to delete an API key +programmatically. + +:::tip + +Tenant administrators can view all API keys created for the tenant. Users are limited to actions for their own API keys. +To learn more about the API key management tasks you can perform as a tenant administrator, refer to the +[Tenant API Key Management](../../tenant-settings/api-key-management.md) page. + +::: + Check out the following resources to enable SSO in Palette with the supported Identity Providers (IDP). ## Resources