Skip to content

basic-secrets-configuration-in-a-clustergroup.adoc

Latest commit

 

History

History
196 lines (137 loc) · 9.21 KB

basic-secrets-configuration-in-a-clustergroup.adoc

File metadata and controls

196 lines (137 loc) · 9.21 KB

Basic secrets configuration in a ClusterGroup

The secrets required for a pattern are not directly represented in the ClusterGroup configuration. Instead, the values-secret.yaml.template file located in the root of validated patterns specifies the necessary secrets, detailing the required data types and keys for each pattern.

In this template file, the secrets key contains an array of secrets. Each secret includes an array of fields, where each field has a name and value that describe the structure of the secret as used by the pattern.

The pattern framework uses the configured SecretStore backend to inject the secrets into the configured backend. Additionally, values can be retrieved in other ways than specifying a string value. This is convenient when the secret material, such as SSH private and/or public keys, already exists as a file elsewhere on the machine from which the pattern is being installed. The framework also supports encoding the field using base64, which is required for binary data files, such as Red Hat Satellite-style manifests.

Secret file processing in the framework

The secrets loader in the framework, triggered by make load-secrets (also run as part of make install), searches for files in the following order and uses the first one found:

  • ~/.config/validatedpatterns/values-secret-{{ pattern_name }}.yaml

  • ~/.config/validated-patterns/values-secret-{{ pattern_name }}.yaml

  • ~/values-secret-{{ pattern_name }}.yaml

  • ~/values-secret.yaml

  • {{ pattern_dir }}/values-secret.yaml.template

Here, “pattern_name” refers to the pattern name (for example, “ansible-edge-gitops”, “industrial-edge”), and “pattern_dir” is the root directory of the locally checked-out pattern. This scheme allows for separate secret files for different patterns or a single file for all patterns. If the secrets file is encrypted, the load-secrets process prompts for the password. When entered, the process will continue and the secrets will be loaded.

Values secret file structure

The values secret file comprises top-level keys and sub-parameters, facilitating the management of secrets within the backend.

Top-Level keys:

  • version: (Optional): Must be “2.0” if specified. Defaults to a deprecated 1.0 schema if not specified.

  • backingStore: (Optional): Defaults to the backingStore configured in values-global. If specified, it must match values-global. It is best not to include it.

  • vaultPolicies: (Optional): Allows injecting vault policies for automatic password generation; effective only when the secrets backend is vault. It’s a dictionary, allowing multiple policies.

  • secrets: The actual secrets to inject into the backend, with each secret having various sub-fields as described below.

Sub-parameters

  • name: Indicates the name of the secret within the backend.

  • fields: Defines the fields within the secret object. Each field has a name and a value. In the template file, the value is used as a placeholder to define the use of the field. This is used by the framework in error messages related to the field.

  • targetNamespaces: (Optional, effective with “Kubernetes” or “none” backends): Secret objects are created in all specified namespaces. Multiple namespaces are allowed as the same secret material may need to be injected into multiple secret objects in different namespaces.

  • labels: (Optional, effective with “Kubernetes” and “none” backends): Kubernetes labels to add to secret objects created through the framework.

  • annotations: (Optional, effective with “Kubernetes” and “none” backends): Kubernetes annotations to add to secret objects created through the framework.

  • type: (Optional, effective with “Kubernetes” and “none” backends): Kubernetes “type” of secret object. Defaults to “Opaque” if unspecified.

  • vaultPrefixes: (Optional, only effective with vault backend): Keys in vault belong to prefixes, allowing creation of the same key with multiple prefixes.

Fields sub-parameters

  • name: Each field in a secret must have a unique, descriptive name (for example, username, password, manifest_content).

  • value: (Optional, technically): Actual secret material. Can be provided via equivalent convenience functions. Value designates content directly, but the framework can also use file contents or parse an ini-file for data. In the template yaml, we always specify value with a description of the name/value pair.

  • path: (Optional): Local file to use as secret content. Framework understands ~ (user home directory) expansion under Linux, Mac, and WSL for convenience.

  • ini_file: (Optional) : Ini-file to retrieve secret material from. Must also include ini_key.

  • ini_key: (Optional): Ini_key within the ini file to retrieve secret material from.

  • ini_section: (Optional): Ini_section within an ini_file to retrieve the key from. Needed only for ini files with multiple sections.

  • base64: (Optional): Boolean value (true/false, default is false) to base64-encode secret material before sending it to the secrets backend. This is independent of the other options, so you can specify plaintext file path and not specify base64 for encoding, or specify a binary file along with base64: true for encoding.

  • onMissingValue: (Optional): (error/prompt/generate) Specifies behavior when the values secret file does not contain a value for the field. By default it throws an error. The “prompt” option asks user to input a secret on the keyboard. The “generate” option uses vault’s secret generation feature to create a suitable secret.

  • override: (Optional, only effective with vault backend): When onMissingValue is set to “generate” and a secret has already been generated, ensures a new one is generated each time the secrets loader is run.

  • vaultPolicy: (Optional; only effective with vault backend): Defines the vault policy (which defines allowable character types and overall length) to use when generating a secret.

Examples:

Here are examples demonstrating the template file from AnsibleEdge GitOps and reasonable ways to provide the secret values using the convenience mechanisms provided by the framework. Alternatively, values can be directly filled in using the value field with the literal contents of each secret.

Template File:

version: "2.0"
secrets:
  - name: aws-creds
    fields:
    - name: aws_access_key_id
      value: "An aws access key that can provision VMs and manage IAM (if using portworx)"

    - name: aws_secret_access_key
      value: "An aws access secret key that can provision VMs and manage IAM (if using portworx)"

  - name: kiosk-ssh
    fields:
    - name: username
      value: 'Username of user to attach privatekey and publickey to - cloud-user is a typical value'

    - name: privatekey
      value: 'Private ssh key of the user who will be able to elevate to root to provision kiosks'

    - name: publickey
      value: 'Public ssh key of the user who will be able to elevate to root to provision kiosks'

  - name: rhsm
    fields:
    - name: username
      value: 'username of user to register RHEL VMs'
    - name: password
      value: 'password of rhsm user in plaintext'

  - name: kiosk-extra
    fields:
    # Default: '--privileged -e GATEWAY_ADMIN_PASSWORD=redhat'
    - name: container_extra_params
      value: "Optional extra params to pass to kiosk ignition container, including admin password"

  - name: cloud-init
    fields:
    - name: userData
      value: |-
        #cloud-config
        user: 'username of user for console, probably cloud-user'
        password: 'a suitable password to use on the console'
        chpasswd: { expire: False }

  - name: aap-manifest
    fields:
    - name: b64content
      path: 'full pathname of file containing Satellite Manifest for entitling Ansible Automation Platform'
      base64: true

Providing values in a “real” values-secret.yaml:

version: "2.0"
secrets:
  - name: aws-creds
    fields:
    - name: aws_access_key_id
      ini_file: ~/.aws/credentials
	ini_key: aws_access_key_id

    - name: aws_secret_access_key
      ini_file: ~/.aws/credentials
	ini_key: aws_secret_access_key

  - name: kiosk-ssh
    fields:
    - name: username
      value: 'cloud-user'

    - name: privatekey
      path: ~/.ssh/id_cloud_user

    - name: publickey
      Path: ~/.ssh/id_cloud_user.pub

  - name: rhsm
    fields:
    - name: username
      value: 'rhsm-user'
    - name: password
      value: 'rhsm-password'

  - name: kiosk-extra
    fields:
    # Default: '--privileged -e GATEWAY_ADMIN_PASSWORD=redhat'
    - name: container_extra_params
      value: "--privileged -e GATEWAY_ADMIN_PASSWORD=B3tt3RP8ssw@rd"

  - name: cloud-init
    fields:
    - name: userData
      value: |-
        #cloud-config
        user: 'cloud-user'
        password: 'aaaa-bbbbb-ccccc-ddddd'
        chpasswd: { expire: False }

  - name: aap-manifest
    fields:
    - name: b64content
      path: '~/manifest_Pattern_20240605T170000Z.zip'
      base64: true