Skip to content

Provision certificates to Google Secret Manager

Provision a certificate from Certificate Manager - SaaS to Google Secret Manager, where it's 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.

Before you begin

  • A Google Secret Manager machine that you created and whose status is Verified.
  • The certificate to provision in the Certificate Manager - SaaS inventory, with its private key.
  • The System Administrator or PKI Administrator role, or the Resource Owner role and membership in the machine's owning team.
  • The ID of the Google Cloud project that holds or will hold the secret, with the provisioning permissions listed in Create a Google Secret Manager machine granted to the machine's service account.

To provision a certificate to Google Secret Manager

  1. Sign in to Certificate Manager - SaaS.
  2. Click Installations > Machines.
  3. Click the more options button at the end of the machine's row, and then select Provision.
  4. In Search a certificate by name, expiration or fingerprint, enter part of the certificate's name, expiration date, or fingerprint, and then select the certificate from the results. Confirm that it's the right certificate by checking Subject DN, Validity, and Certificate SHA1 Fingerprint.

    The rest of the Provision a certificate dialog appears after you select a certificate.

  5. Under Certificate 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. (Optional) In Location, replace the default, global, with a region, such as europe-west1, for a regional secret. 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. For Storage Format, choose 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 chose PKCS#12 or Java KeyStore (JKS), in Keystore Password, enter the password that protects the file. The password is required for these formats.

    Note

    Certificate Manager - SaaS encrypts the credentials you enter and doesn't display them again. On the machine's Properties tab, they appear masked. To keep a stored credential when you edit the machine, leave its masked value unchanged. Keep your own secure record of the credentials in case you need them again.

    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, choose another storage format. JKS secrets are discovered.

  10. If Location is global, for Replication Policy, choose how to replicate 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) Select 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. Under Installation Endpoint, leave Secret Resource Name and Version Name empty. They're read-only, and discovery fills them in.
  14. (Optional) To save the installation without pushing the certificate now, disable Push certificate on save.
  15. Click Save. To save and then provision another certificate, click Save & New.

After you save, Certificate Manager - SaaS pushes the certificate to Google Secret Manager as a new version of the secret, and then checks that the secret's latest version is enabled, so applications can read it. An installation appears on the machine's Installations tab. To provision on a schedule instead of right away, set up a machine provisioning schedule.

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 Coordinated Universal Time (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 errors

If provisioning fails, find the start of its message in the following table.

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 Choose 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 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.