spectrocloud · karl-cardenas-coding · Sep 17, 2024 · Sep 17, 2024
@@ -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)
@@ -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 `<your-palette-host-url>` with your
+    Palette URL, such as `console.spectrocloud.com`, and `<your-palette-api-key>` with your API key.
+
+    ```bash
+    export PALETTE_API_KEY=<your-palette-api-key>
+    export PALETTE_HOST=<your-palette-host-url>
+    ```
+
+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=<your-palette-api-key> PALETTE_HOST=<your-palette-host-url> 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.
@@ -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)
@@ -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)