iagctl create secret

Create a new secret.

The iagctl create secret command stores sensitive information in the gateway. The gateway currently uses secrets for private repository SSH keys.

The gateway’s secrets manager uses asymmetric encryption and stores only the encrypted value in the database. You must use a unique encryption key file to encrypt and decrypt secrets. If you lose the encryption key file, you can’t recover any stored secrets.

For more information, see Create Gateway secret store.

The iagctl create secret command supports two storage modes:

• Local secrets — the value is encrypted at rest using a key file you control. Use this mode for SSH keys, PyPI/Ansible Galaxy credentials, and other values managed directly by Itential Gateway.
• External secret aliases — the value is never stored locally. Itential Gateway records a reference to a secret in an external provider and fetches the plaintext at execution time. Use --provider, --secret, and optionally --key to create an alias.

For more information, see External secrets overview.

Syntax

$
iagctl create secret <secret-name> [flags]

Set up secret encryption

Before you create local secrets, you need to generate an encryption key file and configure the gateway to use it.

Generate an encryption key file

Generate a robust, random encryption key. The following method is one option:

$
openssl rand -base64 256 > /Users/gatewayuser/.gateway.d/gateway_secret.key

For improved security, restrict the file permissions:

$
chmod 400 /Users/gatewayuser/.gateway.d/gateway_secret.key

Configure the gateway to use the encryption key file

You can provide the encryption key file location to the gateway in two ways:

• Command line flag: Use the --encryption-file flag with iagctl create secret and iagctl describe secret. This approach works well for initial setup.

• Configuration variable: For permanent access, set the encryption key file location using the GATEWAY_SECRETS_ENCRYPT_KEY_FILE environment variable or your gateway configuration file. The gateway needs permanent access to the encryption key file to run services that require stored secrets.

1
  [secrets]
2
  encrypt_key_file = /Users/gatewayuser/.gateway.d/gateway_secret.key

Examples

Create a local secret with the encryption file flag

The following example creates a secret called my-secret and encrypts the literal text sensitive data using the file specified by --encryption-file:

$
iagctl create secret my-secret \
>
--value "sensitive data" \
>
--encryption-file /Users/gatewayuser/.gateway.d/gateway_secret.key

Create a local secret with the encryption file configuration variable

The following example creates a secret called my-secret and encrypts the literal text sensitive data. This command assumes you’ve already set the GATEWAY_SECRETS_ENCRYPT_KEY_FILE configuration variable:

$
iagctl create secret my-secret \
>
--value "sensitive data"

Create a local secret from a file

The following example creates a secret called git-key and encrypts the contents of the file /Users/gatewayuser/.ssh/gateway_git_rsa using the @ prefix syntax. This command assumes you’ve already set the GATEWAY_SECRETS_ENCRYPT_KEY_FILE configuration variable:

$
iagctl create secret git-key \
>
--value @/Users/gatewayuser/.ssh/gateway_git_rsa

Create an external secret alias (Vault)

The following example creates an alias called iosxr-vault that retrieves the iosxrpass field from the inv_secrets secret in the vault-prod provider. The value is fetched from Vault at execution time — nothing is stored locally:

$
iagctl create secret iosxr-vault \
>
  --provider vault-prod \
>
  --secret inv_secrets \
>
  --key iosxrpass

Create an external secret alias (Vault, full secret as JSON)

Omit --key to return the full secret data map as a JSON string at execution time:

$
iagctl create secret inv-all \
>
  --provider vault-prod \
>
  --secret inv_secrets

Create an external secret alias (CyberArk)

For CyberArk providers, the --secret value is SafeName/ObjectName:

$
iagctl create secret db-password \
>
  --provider cyberark-prod \
>
  --secret "ProdSafe/DB_Production_Password"

Create an external secret alias (CyberArk, with field extraction)

When the CyberArk object value is a JSON map, use --key to extract a specific field:

$
iagctl create secret db-password \
>
  --provider cyberark-prod \
>
  --secret "ProdSafe/DB_Production_Password" \
>
  --key password

Options

$
  --description string       A brief description of the secret
$
  --encryption-file string   The file to use for encrypting the secret. Clients and runners need this file for decryption. (local secrets)
$
  -h, --help                 Help for secret
$
  --key string               The field to extract when the secret value is a JSON object (external secret aliases)
$
  --provider string          The name of a configured secret provider (external secret aliases)
$
  --secret string            The secret identifier in the external provider (external secret aliases). For Vault, this is the path within the secrets mount. For CyberArk, this is SafeName/ObjectName. For plugin providers, this value is passed directly to the plugin.
$
  --tag stringArray          Metadata tags to associate with the secret
$
  --value string             The secret value to encrypt. Prefix with '@' to read from a file. (local secrets)

Options inherited from parent commands

$
  --profile string   Specify the client profile to use (case-insensitive, defaults to [client] section)
$
  --config string    Path to the configuration file
$
  --raw              Display the result of the command in raw format
$
  --verbose          Enable verbose output