Secrets Management with Kubiya CLI

This guide provides comprehensive instructions for managing sensitive data and secrets securely with the Kubiya CLI.

Understanding Secrets in Kubiya

Secrets in Kubiya are encrypted pieces of sensitive information that can be securely stored, referenced, and used in your tools and automations without exposing their values. Common examples include:

• API keys and access tokens

• Database credentials

• Authentication certificates

• Environment-specific configurations

• Service account credentials

Listing Secrets

To view all secrets in your organization:

kubiya secret list

For JSON format output:

kubiya secret list --output json

Creating Secrets

Creating a Secret with a Value

To create a new secret with a directly specified value:

kubiya secret create --name "aws-access-key" \
                    --value "AKIAIOSFODNN7EXAMPLE" \
                    --description "AWS access key for deployment automation"

Creating a Secret from a File

For larger secrets or to avoid having the secret in your shell history:

kubiya secret create --name "ssh-key" \
                    --from-file ~/.ssh/id_rsa \
                    --description "SSH private key"

Required Parameters:

• --name: A unique name for your secret

One of these is required:

• --value: The sensitive value to store securely

• --from-file: Path to a file containing the secret value

Optional Parameters:

• --description: Description of the secret's purpose

• --tags: Tags for categorizing secrets

• --expiry: Expiration date for the secret (YYYY-MM-DD)

Getting Secret Information

Viewing Secret Metadata

To get metadata about a specific secret (without exposing its value):

kubiya secret get SECRET_NAME

This shows the secret's metadata, such as creation date, description, and tags, but not the actual secret value.

Retrieving a Secret Value

To retrieve the actual value of a secret (use with caution):

kubiya secret value SECRET_NAME

For JSON format output:

kubiya secret value SECRET_NAME --output json

Editing Secrets

In Your Default Editor

To edit a secret's value in your preferred text editor:

kubiya secret edit SECRET_NAME

This will open your default editor (set by $EDITOR environment variable, defaults to vim if not set) with the current secret value, allowing you to make changes securely.

Updating Secret Value

To modify an existing secret value directly:

kubiya secret update SECRET_NAME --value "new-secret-value"

Updating from a File

kubiya secret update SECRET_NAME --from-file path/to/new-value.txt

Updating Metadata Only

To update only the metadata:

kubiya secret update SECRET_NAME --description "Updated description"

Deleting Secrets

To remove a secret:

kubiya secret delete SECRET_NAME

You'll be prompted to confirm the deletion.

To bypass confirmation:

kubiya secret delete SECRET_NAME --force

Using Secrets in Tools

Secrets can be referenced in tool definitions using the $secret: prefix:

# tool-definition.yaml
name: "aws-deploy"
description: "Deploy to AWS"
inputs:
  - name: "region"
    description: "AWS region"
    type: "string"
    default: "us-west-2"
environment:
  AWS_ACCESS_KEY_ID: "$secret:aws-access-key"
  AWS_SECRET_ACCESS_KEY: "$secret:aws-secret-key"
script: "../scripts/deploy.py"

When this tool is executed, Kubiya securely injects the secret values into the environment variables without exposing them.

Rotating Secrets

It's a security best practice to regularly rotate your secrets:

kubiya secret rotate SECRET_NAME --value "new-rotated-value"

To generate a secure random value:

kubiya secret rotate SECRET_NAME --generate

Secret Security Measures

Encryption

Kubiya encrypts all secrets using industry-standard encryption algorithms. The secrets are never stored in plaintext.

Access Control

Only authorized users with the appropriate permissions can access or use secrets. You can manage permissions in the Kubiya dashboard.

Audit Trail

All operations involving secrets (creation, usage, updates, deletions) are logged in the audit trail:

kubiya secret audit SECRET_NAME

Safe File Handling

When editing secrets with the edit command:

• Temporary files are created for editing

• These files are automatically deleted after editing is complete

• The files are created with appropriate permissions to prevent unauthorized access

Secret Scopes

Secrets can be scoped to specific contexts:

Organization-wide Secrets

Available to all teammates and tools:

kubiya secret create --name "global-api-key" --value "value" --scope organization

Teammate-specific Secrets

Available only to specific teammates:

kubiya secret create --name "teammate-api-key" --value "value" --scope teammate --teammate-id TEAMMATE_ID

Source-specific Secrets

Available only to tools from specific sources:

kubiya secret create --name "source-api-key" --value "value" --scope source --source-id SOURCE_ID

Importing and Exporting Secrets

Importing Multiple Secrets

You can import multiple secrets from a JSON file:

kubiya secret import secrets.json

Example secrets.json format:

[
  {
    "name": "api-key-1",
    "value": "secret-value-1",
    "description": "API Key for Service 1"
  },
  {
    "name": "api-key-2",
    "value": "secret-value-2",
    "description": "API Key for Service 2"
  }
]

Exporting Secrets (Metadata Only)

To export secret metadata (without values) for backup or migration:

kubiya secret export --output secrets-metadata.json

Integration with External Secret Managers

Kubiya can integrate with external secret management services:

AWS Secrets Manager

kubiya secret create --name "aws-secret" --from-aws-secret "arn:aws:secretsmanager:region:account:secret:name"

Hashicorp Vault

kubiya secret create --name "vault-secret" --from-vault "secret/data/my-secret" --vault-key "api_key"

End-to-End Example: Setting Up Secure CI/CD Pipeline with Secrets

Here's a complete workflow for managing secrets in a CI/CD pipeline:

Step 1: Create the Required Secrets

# Create AWS deployment credentials
kubiya secret create --name "aws-access-key" --interactive
kubiya secret create --name "aws-secret-key" --interactive

# Create database credentials
kubiya secret create --name "db-username" --value "app_user"
kubiya secret create --name "db-password" --interactive

# Create certificate from file
kubiya secret create --name "ssl-cert" --from-file ./certs/server.crt --description "SSL certificate"

# Create API keys for external services
kubiya secret create --name "notification-api-key" --value "ntfy-key-xyz" --description "API key for notification service"

Step 2: Create a Deployment Tool That Uses Secrets

Create a tool definition file with secret references:

# deploy.yaml
name: "deploy-app"
description: "Full application deployment with DB migrations"
inputs:
  - name: "environment"
    description: "Deployment environment"
    type: "string"
    enum: ["dev", "staging", "prod"]
    required: true
  - name: "version"
    description: "Application version"
    type: "string"
    required: true
environment:
  AWS_ACCESS_KEY_ID: "$secret:aws-access-key"
  AWS_SECRET_ACCESS_KEY: "$secret:aws-secret-key"
  DB_USERNAME: "$secret:db-username"
  DB_PASSWORD: "$secret:db-password"
  NOTIFICATION_API_KEY: "$secret:notification-api-key"
script: "../scripts/deploy-full.py"

Step 3: Execute the Tool

kubiya tool execute deploy-app --args '{"environment":"staging","version":"1.2.3"}'

The deployment runs with all the necessary credentials, but the secret values are never exposed in logs or terminal output.

Step 4: Update a Secret When Needed

If you need to update a secret credential:

# Interactive editing in your preferred editor
kubiya secret edit aws-access-key

# Or direct update
kubiya secret update aws-access-key --value "NEW-ACCESS-KEY"

Step 5: Rotate Secrets Regularly

Set up a scheduled task to remind you to rotate secrets:

# Example webhook that triggers a notification for secret rotation
kubiya webhook create --name "secret-rotation-reminder" \
                     --description "Monthly reminder to rotate secrets" \
                     --tool "send-rotation-notification"

Step 6: Audit Secret Usage

Review the audit logs to ensure proper secret usage:

kubiya secret audit --since "2023-01-01"

For more information on secrets management, visit the official documentation.