Specifying the Secrets to Fetch from Secret Server or Secret Server on the Delinea Platform

You use an ExternalSecret configuration (a YAML file) to specify the secrets that you want to fetch from Secret Server into Kubernetes. The ExternalSecret configuration lets you specify whether or to retrieve the entire secret content or a specific field value from the secret.

To retrieve the entire secret content in JSON format to a Kubernetes Secret, leave the spec.data.remoteRef.property field in your ExternalSecret configuration blank or remove this field from the ExternalSecret configuration. For more details and examples, see the "Working with Plain Text ItemValue Fields" and "Preparing your secret" sections of the Delinea Secret-Server/Platform document in the Kubernetes ESO GitHub repo.

The integration supports retrieval of JSON secret field values (those that are stored in JSON format in Secret Server) and field values in non-JSON formats, such as plain text, password, and URLs. To retrieve the value of a secret field to a Kubernetes secret, provide the field name or the field slug name in spec.data.remoteRef.property. For more details and examples, see the "Working with Plain Text ItemValue Fields" and "Preparing your secret" sections of the Delinea Secret-Server/Platform document in the Kubernetes ESO GitHub repo.

You can fetch a multiple-item secret where the JSON object for the secret contains multiple item structures for the different secret fields. You can retrieve individual secret fields from such a multiple-item secret or the entire secret content with all the fields. For more information and examples, see the Referencing Secrets in multiple Items secrets section of the Delinea Secret-Server/Platform document in the Kubernetes ESO GitHub repo.

Retrieving a specific version of a secret is not yet supported.

The following sections detail how to perform the sequential steps involved in creating an ExternalSecret configuration: 

  1. Create an ExternalSecret configuration YAML file.

  2. Modify the ExternalSecret configuration for the different use cases supported by the Kubernetes ESO integration.

  3. Apply the ExternalSecret configuration to your cluster.

Step 1: Creating an ExternalSecret Configuration

The following procedure describes how to create an ExternalSecret configuration for the different supported use cases. The Delinea Secret-Server/Platform document in the Kubernetes ESO GitHub repo provides examples of the ExternalSecret configuration that you can use to create your ExternalSecret configuration.

To create an ExternalSecret configuration:

  1. Create a YAML file for your ExternalSecret configuration.

  2. Depending on your use case, copy the content from the ExternalSecret configuration example from the specified section of the Delinea Secret-Server/Platform document into your YAML file.

    Use Case Copy the ExternalSecret Configuration Example from This Section
    Retrieve a secret by secret ID "Referencing Secrets"
    Retrieve a secret by secret name "Referencing Secrets"
    Retrieve a secret by path "Support for Fetching Secrets by Path"

Step 2: Modifying the ExternalSecret Configuration

After you create an ExternalSecret configuration, you must modify it to specify the secret that you want to fetch from Secret Server. The following procedure describes how to set the fields in the ExternalSecret configuration for the different supported use cases.

To modify the ExternalSecret configuration:

  1. Open the ExternalSecret configuration YAML file.

  2. Set the fields in the ExternalSecret configuration as follows:

    Field How to Set the Field for Different Use Cases
    metadata.name

    All use cases

    Specify the name of your ExternalSecret configuration (for example, secret-server-external-secret).
    spec.data.secretStoreRef.name 

    All use cases

    Specify the name of your SecretStore configuration (for example, my-secret-store-store).
    spec.data.secretKey This field specifies the key in a Kubernetes Secret where the retrieved secret will be stored. Do not change the SecretServerValue value.
    spec.data.remoteRef.key

    Retrieve a secret by secret ID

    Provide the ID of the secret to fetch (for example, 52622).

    To find the ID of a secret in Secret Server, in the browser's address bar, note the secret ID located in the URL of the secret details page (it will appear after secrets).

    Retrieve a secret by secret name

    Provide the name of the secret to fetch (for example, my-external-secret). Make sure that the secret name doesn't contain spaces or control characters.

    Retrieve a secret by path

    Specify the path (the full folder hierarchy) of the secret to fetch from Secret Server in the format /FolderName/SecretName. Make sure that the path exactly matches the folder and secret name in Secret Server and that the path doesn't contain spaces and control characters.

    spec.data.remoteRef.property

    All use cases

    To retrieve a specific field value from the secret, provide the field name or the field slug name. To retrieve the entire secret content in JSON format, leave this field blank or remove it from the ExternalSecret configuration. For details and examples, see the "Working with Plain Text ItemValue Fields" and "Preparing your secret" sections of the Delinea Secret-Server/Platform document in the Kubernetes ESO GitHub repo.

  3. Save the YAML file.

Step 3: Applying the ExternalSecret Configuration to Your Cluster

After you have modified the ExternalSecret configuration for your use case, you must apply it to your cluster. This fetches the specified secret from Secret Server, creates a Kubernetes Secret in your cluster, and injects the retrieved secret value into the Secret.

To apply the ExternalSecret configuration to your cluster:

  1. In a terminal window, change to the directory where you saved the ExternalSecret configuration YAML file.

  2. Run the following command to apply the YAML file with your ExternalSecret configuration to your cluster.

    kubectl apply -f "<file-name>.yaml"