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 3e198b7535..7de6813c5d 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 @@ -16,6 +16,43 @@ Tenant administrators have additional permissions and capabilities to manage API revoke, and delete API keys for any user within the tenant. Each of these actions is described in detail in the following resources. +## 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 - [Create API Key](create-api-key.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