Working with Secrets

You use secrets in an inventory to protect sensitive information from anyone who does not have the rights to see this information.

The secret values protected by nevisAdmin 4 cannot be individually modified or viewed in the inventory once they are inserted; they are stored in the database in encrypted form. However, it is possible to modify and view the secret values in the Secret & Files screen if you have the required permissions. For more details, see the chapter Secrets & Files.

info

Protecting passwords

For example, consider a component that needs to connect to a database. Instead of putting the password as plain text in the inventory file, you can add it as a secret variable in the inventory.

caution

Passwords are visible in generated configuration files, for example in the deployment wizard.

However, for Kubernetes deployments, if the secret is used in secret fields (secret properties), these secrets are not exposed, they are not visible in Git or the generated configuration files. This is done by mapping the secrets used in the inventory to corresponding Kubernetes secrets, then mounting them into the component containers, where they are used to resolve the secrets in the generated configuration files. For more information about the secret fields, see chapter Special Input Field Type: Secret fields.

Inserting a Secret

There are several ways to add a secret to an inventory:

• Via the Insert secret button in the Inventory Editor. This will create an inventory level secret, which you can only use in the given inventory.
• By using an existing secret (on a global or inventory level).
  • Using a global secret: Global secrets can be used in multiple inventories. To use a global secret, refer to it from the given inventory. If the global secret does not exist yet, create it via the Create global secret button in the Secret & Files screen. To open this screen, go to the sidebar of the Administration tab, and select Secret & Files from the Global Settings menu. For more information, see the chapter Secrets & Files.
  • Using an existing inventory level secret: To use an existing secret on inventory level, the secret must have been used in the given inventory before.

Inserting a new secret value into an inventory

To insert a new secret value into an inventory, perform the next steps:

1. Put you cursor right after the variable name inside a vars block, for example after __connection_password: .
2. Click the Insert secret button.
3. The Insert secret dialog opens. Enter the secret value for this variable in the Define secret for variable <var name> input field.
4. Add a description, if needed. The description will be visible in Secret & Files screen and also in the Inventory Editor on hovering over the inserted secret value.
5. Click Insert secret to add the secret value to the variable in the inventory file.
6. Click on Save changes in the lower right corner of the inventory file.

The following movie demonstrates the steps you need to perform. As an example, a secret is inserted for the __connection_password variable for SSH connections.

Note that it is usually more secure to configure key-based authentication. For more information, see Deployment via SSH.

Using an already existing global secret

There are several ways to use an already existing global secret.

• By manually copy-pasting the reference ID into the inventory. For this, perform the following steps:

  1. Open the Secrets & Files screen and find your global secret in the table.
  2. Copy the reference ID (secret ID).
  3. Click inside the inventory file in the Inventory Editor.
  4. Put you cursor right after the variable name inside a vars block, for example after __connection_password: .
  5. Paste the reference ID to the variable as a value.
  6. Click on Save changes in the lower right corner of the inventory file.

• By selecting the existing global secret from the list. For this, perform the following steps:

  1. Click inside the inventory file in the Inventory Editor.
  2. Put you cursor right after the variable name inside a vars block, for example after __connection_password: .
  3. Click on the Insert secret button.
  4. Select the existing global secret from the select existing secret dropdown.
  note

  You can still reuse a secret that was previously removed from the inventory. The secret only becomes unusable when it is removed from the Secret & Files screen.

  5. Click Insert secret to add the secret value to the variable in the inventory file.
  6. Click on Save changes in the lower right corner of the inventory file.

The following movies demonstrate the two possible ways of inserting an existing global secret.

Selecting an already existing inventory level secret

To use an already existing inventory level secret, perform the following steps:

1. Click inside the inventory file in the Inventory Editor.
2. Put you cursor right after the variable name inside a vars block, for example after __connection_password: .
3. Click on the Insert secret button.
4. Select the existing inventory level secret from the select existing secret dropdown.

note

You can still reuse a secret that was previously removed from the inventory. The secret only becomes unusable when it is removed from the Secret & Files screen.

5. Click Insert secret to add the secret value to the variable in the inventory file.
6. Click on Save changes in the lower right corner of the inventory file.

The following movie demonstrates the steps you need to perform.

Variable values can contain multiple secret references mixed with regular text.

Scope of secrets

Secrets are only resolvable in the inventory they were created in. Copying a secret reference (secret://...) from one inventory to another will not make the secret's value available in the other inventory. Similarly, branching an inventory manually in your Git system and importing it will result in an inventory with unresolvable secrets.

Removing a Secret

If you no longer need a specific secret value, you can simply remove the reference (secret://...) from the inventory.

Note that this will not delete the secret from the database. The reason is that you may still need the secret when you roll back to an older version of the inventory. All secrets, including removed secrets, are permanently deleted from the database when you delete the inventory.

Inserting a Kubernetes secret

Secrets defined directly in Kubernetes, using the kubectl create secret command, can be also referenced in inventories. To do so, use the format k8s-secret**://<Kubernetes secret key>:<keymap key>/, where <Kubernetes secret key> is the name given to the Kubernetes secret, and <keymap key> is the key of the individual secret stored in the Kubernetes secret. Do not forget to include the trailing / character at the end of the reference.

This is currently supported only for the secrets used in the secret fields (secret properties), see more on secret fields at chapter Special Input Field Type: Secret fields.

Secrets referenced this way will be searched for and replaced during deployment, but they will not be exposed during the deployment preview, or upon publishing to Git.

Removing a Kubernetes secret

Removing a Kubernetes secret reference from the inventory will not delete the secret from the cluster. This has to be done manually, using the kubectl delete secret command.

How Secrets Work

If you want to understand how secrets work in more detail, see Encryption and Storage of Secrets.