Getting Started with CredHub Maestro

Page last updated:

This topic describes setting up and using CredHub Maestro for CredHub.

Overview

CredHub Maestro is a command-line interface (CLI) that facilitates rotations of 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

CredHub Maestro is available in Pivotal Platform Ops Manager v2.8 and later.

To use Maestro outside Ops Manager environments, contact Pivotal Support.

Set Up Environment Variables

This section describes setting up the environment variables you need to use CredHub Maestro.

Required Environment Variables

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 URL or IP address of BOSH director
BOSH_CLIENT Name of BOSH client
BOSH_CLIENT_SECRET BOSH client secret
BOSH_CA_CERT Path or value of BOSH Director trusted CA certificate
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.

Using CredHub Maestro from Outside Your Foundation

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

Optional Environment Variables

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

Commands

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

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 Certificate Authorities (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

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 topology expected

maestro topology expected shows the expected topology that would result from a BOSH deployment.

You can use the following flags with maestro topology expected:

  • deployment-names: Allow expected topology to reflect a selective deployment. This must be a comma-separated list.

maestro regenerate

maestro regenerate regenerates CredHub managed certificates. By default, certificates that have been set in CredHub are not regenerated.

maestro regenerate ca

maestro regenerate ca regenerates actively deployed CAs.

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.

maestro regenerate leaf

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.

maestro update-transitional

maestro update-transitional updates the transitional flag for CAs.

maestro update-transitional latest

maestro update-transitional latest updates the transitional flag for the latest version of the actively deployed CA.

You can use the following flags with maestro update-transitional latest:

  • all: Update the transitional flag for all actively deployed CAs.

  • name: Update 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.

maestro update-transitional signing

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.

maestro update-transitional remove

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.

maestro garbage-collect

maestro garbage-collect deletes inactive certificate versions.

maestro garbage-collect leaf

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

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.