diff --git a/docs/docs-content/automation/automation.md b/docs/docs-content/automation/automation.md index 26959c7b06..9a3c3bda98 100644 --- a/docs/docs-content/automation/automation.md +++ b/docs/docs-content/automation/automation.md @@ -16,14 +16,17 @@ This section contains documentation and guides for tools essential in automating [self-hosted Palette](../enterprise-version/enterprise-version.md) instance and deploying a [Private Cloud Gateway](../clusters/pcg/pcg.md). +- Palette Go SDK - Enables developers to interact with Palette APIs for automated resource management using Go. + - Palette Terraform Provider - Allows users to use [Terraform](https://www.terraform.io) for automating the deployment and management of Palette resources such as cluster profiles, cloud accounts, clusters, and more. -- Palette Crossplane Provider - It allows users to use [Crossplane](https://docs.crossplane.io/v1.15/) to provision and +- Palette Crossplane Provider - Allows users to use [Crossplane](https://docs.crossplane.io/v1.15/) to provision and manage Palette resources through standard Kubernetes APIs. ## Resources - [Palette CLI](./palette-cli/palette-cli.md) +- [Palette Go SDK](./palette-sdk/palette-sdk.md) - [Palette Terraform Provider](./terraform/terraform.md) - [Palette Crossplane Provider](./crossplane/crossplane.md) diff --git a/docs/docs-content/automation/palette-sdk/list-clusters-sdk.md b/docs/docs-content/automation/palette-sdk/list-clusters-sdk.md new file mode 100644 index 0000000000..1c590645e8 --- /dev/null +++ b/docs/docs-content/automation/palette-sdk/list-clusters-sdk.md @@ -0,0 +1,184 @@ +--- +sidebar_label: "List Clusters with Palette Go SDK" +title: "List Clusters with Palette Go SDK" +description: "Learn how to use the Palette GO SDK to list your Palette host clusters." +hide_table_of_contents: false +sidebar_position: 10 +tags: ["palette-sdk", "go"] +--- + +The Palette Go Software Developer Toolkit (SDK) enables Go developers to interact with Palette services. This guide +explains how to install and use the SDK to list the active host clusters in your Palette environment. + +## Prerequisites + +- [Go](https://go.dev/doc/install) version 1.22.5 or later. + +- A Palette account with [Tenant Admin](../../tenant-settings/tenant-settings.md) access. + +- A Palette API key. Refer to the [Create API Key](../../user-management/authentication/api-key/create-api-key.md) page + for instructions on how to create an API key. + +## List Palette Clusters + +1. Open a terminal window and create a folder for you Go repository. + + ```bash + mkdir sdk-example + ``` + +2. Navigate to the created folder. + + ```bash + cd sdk-example + ``` + +3. Initialize your Go module and enable dependency tracking for your code by issuing the following command. This will + create a `go.mod` file in the current folder. + + ```bash + go mod init example/list-clusters + ``` + +4. Download the required Palette SDK modules. The command below retrieves the modules and records their dependencies in + the `go.mod` file. + + ```bash + go get github.com/spectrocloud/palette-sdk-go/api/models + go get github.com/spectrocloud/palette-sdk-go/client + ``` + +5. Create a source file named `main.go`. + + ```bash + touch main.go + ``` + +6. Open the `main.go` file in a text editor of your choice and paste the content below. + + ```go + package main + + import ( + "fmt" + "os" + + "github.com/spectrocloud/palette-sdk-go/api/models" + "github.com/spectrocloud/palette-sdk-go/client" + ) + + func main() { + + // Read environment variables + + host := os.Getenv("PALETTE_HOST") + apiKey := os.Getenv("PALETTE_API_KEY") + projectUid := os.Getenv("PALETTE_PROJECT_UID") + scope := "tenant" + + if host == "" || apiKey == "" { + fmt.Println("You must specify the PALETTE_HOST and PALETTE_API_KEY environment variables.") + os.Exit(1) + } + if projectUid != "" { + scope = "project" + } + + // Initialize a Palette client + + pc := client.New( + client.WithPaletteURI(host), + client.WithAPIKey(apiKey), + ) + if projectUid != "" { + client.WithScopeProject(projectUid)(pc) + } else { + client.WithScopeTenant()(pc) + } + + // Search for clusters + + fmt.Printf("Searching for Palette clusters with %s scope...\n", scope) + + clusters, err := pc.SearchClusterSummaries(&models.V1SearchFilterSpec{}, []*models.V1SearchFilterSortSpec{}) + if err != nil { + panic(err) + } + + // Display the results + + if len(clusters) == 0 { + fmt.Println("\nNo clusters found.") + return + } + + fmt.Printf("\nFound %d cluster(s):\n", len(clusters)) + for _, cluster := range clusters { + fmt.Printf("\nName: %s\n", cluster.Metadata.Name) + fmt.Printf(" Cloud Type: %s\n", cluster.SpecSummary.CloudConfig.CloudType) + fmt.Printf(" Project: %s\n", cluster.SpecSummary.ProjectMeta.Name) + } + } + ``` + + This application performs the following tasks: + + - Imports the required packages. + + - Reads the environment variables provided by the user to configure the client and define the search scope. If the + user provides a project UID, the application sets the scope to project-specific and lists the active clusters + within that project. If no project UID is given, the scope is set to tenant-wide, listing active clusters across + all projects. + + - Initializes a Palette client using the provided host URL and Palette API key. + + - Searches for Palette clusters within the specified scope (tenant-wide or project-specific). + + - Displays the active clusters with details such as name, cloud type, and associated project. + + After pasting the content, save and exit the file. + +7. Export your Palette host URL and API key as environment variables. Replace `` with your + Palette URL, such as `console.spectrocloud.com`, and `` with your API key. + + ```bash + export PALETTE_API_KEY= + export PALETTE_HOST= + ``` + +8. Issue the following command to execute the application. + + ```bash + go run . + ``` + + :::tip + + Optionally, instead of exporting the variables in a separate command, you can use the `go run` command with + command-scoped environment variables. + + ```bash + PALETTE_API_KEY= PALETTE_HOST= go run . + ``` + + ::: + + The application will print the active clusters in your Palette environment. + + ```text hideClipboard + Searching for Palette clusters with tenant scope... + + Found 1 cluster(s): + + Name: aws-cluster + Cloud Type: aws + Project: Default + ``` + +## Validate + +1. Log in to [Palette](https://console.spectrocloud.com/). + +2. From the left **Main Menu**, click **Clusters**. + +3. Verify that the clusters printed by the Go client application are also visible in the Palette UI. diff --git a/docs/docs-content/automation/palette-sdk/palette-sdk.md b/docs/docs-content/automation/palette-sdk/palette-sdk.md new file mode 100644 index 0000000000..3a94e7eed2 --- /dev/null +++ b/docs/docs-content/automation/palette-sdk/palette-sdk.md @@ -0,0 +1,46 @@ +--- +sidebar_label: "Palette Go SDK" +title: "Palette Go SDK" +description: "Learn how to get started with the Palette Go SDK." +hide_table_of_contents: false +tags: ["palette-sdk"] +--- + +The [Palette Go Software Developer Toolkit (SDK)](https://github.com/spectrocloud/palette-sdk-go) provides Go developers +a user-friendly client for interacting with Palette APIs. + +## Initialize Palette Client + +The Go Palette client supports the following authentication methods. + +- [JWT](https://github.com/spectrocloud/palette-sdk-go/blob/main/client/client.go#L56) +- [Palette API Key](https://github.com/spectrocloud/palette-sdk-go/blob/main/client/client.go#L49) +- [Username](https://github.com/spectrocloud/palette-sdk-go/blob/main/client/client.go#L63) and + [password](https://github.com/spectrocloud/palette-sdk-go/blob/main/client/client.go#L70) + +The snippet below showcases an example of how to initialize the Palette client using an API key. You must provide a +[Palette URI](https://github.com/spectrocloud/palette-sdk-go/blob/main/client/client.go#L77) for all authentication +methods. + +```go + import ( + "github.com/spectrocloud/palette-sdk-go/client" + ) + + pc := client.New( + client.WithPaletteURI(host), + client.WithAPIKey(apiKey), + ) +``` + +## Get Started + +Check out the [List Clusters with Palette Go SDK](./list-clusters-sdk.md) example to learn how to install, configure, +and use the SDK. This guide provides instructions and sample code for listing the active clusters in your Palette +environment. Additionally, refer to the [client](https://github.com/spectrocloud/palette-sdk-go/blob/main/client) folder +for a complete list of client configuration options. + +## Resources + +- [Palette SDK Go](https://github.com/spectrocloud/palette-sdk-go) GitHub repository +- [List Clusters with Palette Go SDK](./list-clusters-sdk.md) 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 616518e169..9112d74e3a 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