Skip to content

Google Secret Manager

Use this procedure to provision a certificate from Certificate Manager - SaaS to a Google Secret Manager machine. Each provisioned certificate is stored as a secret that holds the certificate, its private key, and its chain. When the certificate is renewed, Certificate Manager - SaaS adds a new version to the same secret, so applications that read the secret's latest version get the renewed certificate on their next read, with no restart.

Only certificates whose private key Certificate Manager - SaaS holds can be provisioned.

  1. Sign in to Certificate Manager - SaaS.

  2. Click Installations > Machines.

  3. Click the more options more options button at the right end of the Google Secret Manager machine's row, and then select Provision.

  4. In Search a certificate by name, expiration or fingerprint, search for and select the certificate you want to provision.

    Verify that you selected the correct certificate by reviewing the Subject DN, Validity, and Certificate SHA1 Fingerprint.

  5. Under Secret Information, in Project ID, enter the ID of the Google Cloud project that holds the secret. If the machine has Allowed Project IDs, the project must be on that list.

  6. In Location, enter global for a global secret, or a region, such as europe-west1, for a regional secret. The default is global. A region must be one that Secret Manager offers to the project.

  7. In Secret ID, enter the name of the secret. The name can contain letters, digits, underscores, and hyphens, up to 255 characters. If the secret doesn't exist, Certificate Manager - SaaS creates it.

    Important

    Certificate Manager - SaaS writes only to secrets it manages. If a secret with that name already exists and doesn't carry the label venafi-managed=true, provisioning fails and the existing secret is left untouched. Either choose a different name, or add the label venafi-managed with the value true to the existing secret in Google Cloud.

  8. From Storage Format, select how the certificate, private key, and chain are stored in the secret. Choose the format that the application reading the secret expects:

    Storage format What the secret holds
    JSON (certificate, privateKey, certificateChain) (default) A JSON object in which certificate and privateKey are PEM strings, and certificateChain is a list of PEM strings.
    Kubernetes TLS (tls.crt, tls.key, ca.crt) A JSON object in which tls.crt holds the certificate followed by its chain, tls.key holds the private key, and ca.crt holds the chain, all in PEM.
    PEM The certificate, its chain, and the private key, as consecutive PEM blocks.
    PKCS#12 A password-protected PKCS#12 file.
    Java KeyStore (JKS) A password-protected Java KeyStore with one private key entry, under the alias certificate.

  9. If you selected PKCS#12 or Java KeyStore (JKS), enter the password that protects the file in Keystore Password. The password is required for these formats.

    Note

    Discovery has no keystore password, so it can't open the PKCS#12 secrets that Certificate Manager - SaaS provisions. If you also want to discover these secrets, select another storage format. JKS secrets are discovered.

  10. If Location is global, select a Replication Policy for the new secret:

    • Automatic (default) – Google Cloud chooses where to replicate the secret.
    • User-managed – The secret is replicated only to the regions you choose. In Replica Locations, enter a comma-separated list of regions, for example us-east1,europe-west1.

    These fields don't appear for a regional secret.

  11. (Optional) In Customer-Managed Encryption Key, enter the full name of a Cloud KMS key to encrypt the new secret with, in the form projects/PROJECT/locations/LOCATION/keyRings/RING/cryptoKeys/KEY. If you leave it empty, Google Cloud encrypts the secret with a Google-managed key. The key's location must match where the secret is stored:

    • For a regional secret, the key must be in the secret's region.
    • For a global secret with Automatic replication, the key must be in global.
    • For a global secret with User-managed replication, the key must be in the replica location, and you can enter only one replica location.

    The project's Secret Manager service agent (service-PROJECT_NUMBER@gcp-sa-secretmanager.iam.gserviceaccount.com) needs the Cloud KMS CryptoKey Encrypter/Decrypter role (roles/cloudkms.cryptoKeyEncrypterDecrypter) on the key.

    Important

    Replication Policy, Replica Locations, and Customer-Managed Encryption Key apply only when Certificate Manager - SaaS creates the secret. Changing them later, or pointing an installation at an existing secret, doesn't change how that secret is replicated or encrypted.

  12. (Optional) Turn on Disable Previous Versions to disable every older enabled version of the secret each time Certificate Manager - SaaS adds a new version. By default, older versions stay enabled, so you can roll back to them.

  13. Leave the fields under Secret Version Details empty. Secret Resource Name and Version Name are read-only, and discovery fills them in.

  14. (Optional) To save without pushing the certificate now, turn off Push certificate on save. It's on by default.

  15. Click Save.

    Tip

    You can schedule your provisions daily, weekly, or monthly. See Provision certificates.

After saving, the certificate is pushed to Google Secret Manager as a new version of the secret, and an installation is created on the Installations tab. Certificate Manager - SaaS then checks that the secret's latest version is enabled, so applications can read it.

What to expect in Google Secret Manager

  • Every secret that Certificate Manager - SaaS creates or updates carries these labels:
    • venafi-managed=true
    • venafi-cert-serial – The certificate's serial number, in lowercase hexadecimal. Google Cloud limits label values to 63 characters, so a longer serial number is truncated.
    • venafi-cert-expiry – The certificate's expiration date, as YYYY-MM-DD in UTC.
  • Each push adds a new secret version. The secret name doesn't change. If the latest version already holds the same certificate in the same storage format, Certificate Manager - SaaS doesn't add another version. The chain isn't compared, so a change to the chain alone doesn't add a version.
  • A secret version can be no larger than 64 KiB. If the certificate, chain, and key don't fit, provisioning fails and no version is added. If the secret didn't exist, Certificate Manager - SaaS has already created it, so it stays in Google Cloud with no versions. A very long chain is most likely to exceed the limit in the PKCS#12 or JKS format, so switch to a smaller format such as PEM or JSON.
  • Certificate Manager - SaaS doesn't manage Google Cloud rotation schedules. If a secret that Certificate Manager - SaaS renews has a rotation schedule, remove it, or make sure that nothing that responds to its rotation notifications writes new versions of the secret.
Provisioning failed. What does the message mean?
Message begins with What to do
refusing to overwrite unmanaged secret The secret exists and doesn't carry venafi-managed=true. Add the label to the secret, or enter a different Secret ID.
location "<region>" is not a Secret Manager location of project Secret Manager doesn't offer regional secrets in that region for this project. Use global or a supported region.
KMS key <name> is in location The key's location doesn't match the secret. Use a key in the location described in the Customer-Managed Encryption Key step.
a customer-managed encryption key needs exactly one replica location Enter a single replica location, use Automatic replication, or leave Customer-Managed Encryption Key empty.
the <format> payload is <size> bytes, over the Secret Manager limit Select a smaller storage format, such as PEM or JSON.
the service account lacks permission Add the permission named in the message to the service account's role. See Create a new Google Secret Manager machine.
project <ID> is not in the Allowed Project IDs of this connection Enter a project from the machine's Allowed Project IDs, or add the project to that list.
the latest version <name> is <state>, applications cannot read it The secret's latest version was disabled or destroyed in Google Cloud after the push. Push the certificate again, or re-enable the version.