This topic describes how you can set up and use CredHub Maestro, a command-line interface (CLI) that rotates certificates in CredHub.
Using CredHub Maestro, you can:
Determine if any of your CredHub certificates are expiring soon
Rotate CredHub certificates
Clean up inactive certificate versions so that CredHub does not run out of disk space
This section describes setting up the environment variables you need to use CredHub Maestro.
To set the CredHub environment variables you need to set up CredHub Maestro, follow the guidance in the table below.
To set BOSH environment variables, see Advanced troubleshooting with the BOSH CLI.
Environment Variable | Description |
---|---|
BOSH_ENVIRONMENT | BOSH Director URL or IP address. |
BOSH_CLIENT | Name of BOSH client. |
BOSH_CLIENT_SECRET | BOSH client secret. |
BOSH_CA_CERT | Path or value of BOSH Director trusted certificate authority (CA). |
CREDHUB_SERVER | URL of BOSH Director CredHub server. This should be BOSH_ENVIRONMENT:8844 . |
CREDHUB_CLIENT | Name of CredHub client. This is the same as BOSH_CLIENT . |
CREDHUB_SECRET | CredHub client secret. This is the same as BOSH_CLIENT_SECRET . |
CREDHUB_CA_CERT | Path or value of CredHub trusted CA certificate. This is the same as BOSH_CA_CERT . |
To use CredHub Maestro from outside your foundation, you must also set the following variables in addition to the required environment variables:
Environment Variable | Description |
---|---|
BOSH_ALL_PROXY | SOCKS5 proxy address of BOSH Director jumpbox. |
CREDHUB_PROXY | SOCKS5 proxy address of CredHub jumpbox. |
You can also set the following optional enviroment variables:
Environment Variable | Description |
---|---|
MAESTRO_DEBUG | Enable debug logging. |
MAESTRO_OUTPUT_JSON | Print all CredHub Maestro command output as JSON. |
This section describes the commands you can use in CredHub Maestro.
To review a list of commands in CredHub Maestro, run maestro --help
.
maestro list
displays expiry information for all actively deployed certificates in CredHub.
You can use the following flags with maestro list
:
expires-within
: Filter certificates by expiry window. Valid units are d
for days, w
for weeks, m
for months, and y
for years.
deployment-name
: Filter certificates by deployment name.
name
: Show metadata for a single certificate.
include-all
: Include inactive certificates in response.
ca-only
: Filter certificates that are CAs.
leaf-only
: Filter certificates that are leaf certificates.
generated-only
: Include only certificates that have been generated by CredHub.
The deployment-name
and include-all
flags are mutually exclusive.
maestro topology
displays expiry information for all actively deployed certificates in CredHub.
You can use the following flags with maestro topology
:
name
: Display topology for a single certificate.
include-all
: Display topology for both active and inactive certificates.
maestro regenerate
regenerates CredHub-generated certificates. By default, certificates that have been manually set in CredHub are not regenerated.
maestro regenerate ca
regenerates actively deployed CAs and adds transitional flags to these new CA versions. The transitional status indicates that these new CA versions will not yet sign any leaf certificates, though they will be trusted by clients.
You can use the following flags with maestro regenerate ca
:
all
: Regenerate all actively deployed CAs.
name
: Regenerate a single CA by name.
dry-run
: List CAs to be regenerated.
exclude
: Comma-separated list of CAs to exclude from being regenerated. This includes all leaf certificates of excluded CAs.
force
: Regenerate both CredHub-generated and manually set CAs.
show-excluded
: Show all certificates excluded from regeneration.
maestro regenerate leaf
regenerates actively deployed leaf certificates.
You can use the following flags with maestro regenerate leaf
:
all
: Regenerate all actively deployed leaf certificates.
name
: Regenerate single leaf by name.
signed-by
: Regenerate all actively deployed leaf certificates signed by a specific CA.
dry-run
: List leafs to be regenerated.
exclude-signed-by
: Exclude all leaf certificates signed by a list of CAs from being regenerated.
force
: Regenerate both CredHub-generated and manually set leaf certificates.
show-excluded
: Show all certificates excluded from regeneration.
maestro update-transitional
updates the transitional flag for CAs.
maestro update-transitional signing
updates the transitional flag for the version of the actively deployed CA that signed deployed leaf certificates.
You can use the following flags with maestro update-transitional signing
:
all
: Update the transitional flag for all actively deployed CAs.
name
: Update the transitional flag for a single CA.
dry-run
: List CAs to be updated.
exclude
: Exclude a list of CAs and their leaf certificates from being updated.
show-excluded
: Show all certificates excluded from update.
maestro update-transitional remove
removes the transitional flag for all versions of the actively deployed CA.
You can use the following flags with maestro update-transitional remove
:
all
: Remove the transitional flag for all actively deployed CAs.
name
: Remove the transitional flag for a single CA.
dry-run
: List CAs to be updated.
exclude
: Exclude a list of CAs and their children from being updated.
show-excluded
: Show all certificates excluded from update.
maestro garbage-collect
deletes inactive certificate versions.
maestro garbage-collect leaf
deletes inactive leaf certificate versions that are older than the active certificate version.
You can use the following flags with maestro garbage-collect leaf
:
all
: Remove all inactive versions of deployed leaf certificates.
name
: Remove all inactive versions of a single leaf certificate.
dry-run
: List leaf certificate versions to be removed.
force
: Remove all inactive leaf certificates.
maestro garbage-collect ca
deletes inactive CA versions that are older than the active CA version.
You can use the following flags with maestro garbage-collect ca
:
all
: Remove all inactive versions of deployed CAs.
name
: Remove all inactive versions of a single CA.
dry-run
: List CA versions to be removed.
force
: Remove all inactive CAs.
CredHub Maestro performs basic safety checks when rotating certificates to prevent unsafe operations.
To skip CredHub Maestro safety checks, you can pass the --skip-safety-check
flag to CredHub Maestro certificate rotation commands.
For more information, see Troubleshooting CredHub Maestro Safety Violations During Certificate Rotation.