Package: venafi-vcert-gitlab-integration
Venafi Machine Identity Management integration for GitlabThis plugin integratesVenafi Machine Identity Managementwith Gitlab-based CI/CD processes.Table of contentsUsage overviewSetting up the TPPSetting up executor hosts (shell and SSH executors only)CompatibilityOperationsRequest certificateUsage with Docker executorUsage with shell or SSH executorVariables: generalVariables: subject informationVariables: outputDownload previous certificateUsage with Docker executorUsage with shell or SSH executorVariablesRenewing certificate only when expiration is nearUsage overviewYou must already have access to either Venafi TLS Protect (part of the Venafi Trust Protection Platform™) or Venafi as a Service. This Gitlab integration product requires you to specify the connection address and authentication details.You use this Gitlab integration product by defining, inside your Gitlab CI YAML, jobs call operations provided by this Gitlab integration product.Setting up the TPPThis is not applicable when using Venafi as a Service.If you plan on using this Gitlab integration product in combination with a TPP, then you must setup an API Application Integration:Go to your TPP's Aperture web interface.Go the Platform product.In the top navbar, click API ➜ API Application Integrations.Click "New Application Integration".Under "Type of Integration", select "Vendor Integration". Paste the following JSON:{"id":"qensus-vcert-gitlab","name":"Qensus VCert Gitlab","vendor":"Qensus B.V.","description":"Venafi Machine Identity Management integration for Gitlab","scope":"certificate:manage"}Then click Save.Select the "Qensus VCert Gitlab" integration and click "Edit Access". Grant access to the TPP user account that you want to use from Jenkins.Setting up executor hosts (shell and SSH executors only)If you plan on using this Gitlab integration product in combination with the shell and SSH executors, then you must install the following software on the hosts on which those executors operate. This Gitlab integration product does not take care of installing these prerequisites for you.Install Python >= 3.8. Ensure that it's in PATH.Install pip >= 20.2. This is necessary in order to use the2020 dependency resolver.Install our Gitlab integration package:If you're on pip >= 20.2 but < 20.3, then run:pip install venafi-vcert-gitlab-integration --use-feature=2020-resolverIf you're on pip >= 20.3, then run:pip install venafi-vcert-gitlab-integrationCompatibilityThis product requires Gitlab >= 13.9.This product supports the following Gitlab runner executors:ShellSSHDockerOperationsRequest certificateRequests a pair of certificate + private key. The output is to be written to the specified files, in PEM format.Usage with Docker executorDefine a job that callsvenafi-vcert-request-certificate.Ensure the job operates within the imagequay.io/venafi-gitlab-integration/tlsprotect-vcert. We recommend that you specify atagin order to avoid breaking changes introduced by new major versions.Specify:Connection and authentication details for either a TPP or for Venafi as a Service.Certificate request parameters.Where to store the output.See the variables reference below.request_cert:image:quay.io/venafi-gitlab-integration/tlsprotect-vcert:2-x86_64script:-venafi-vcert-request-certificatevariables:## Specify TPP or Venafi as a Service parametersTPP_BASE_URL:https://my-tppTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.## Specify certificate parametersZONE_CONFIG_NAME:Certificates\\VCertCOMMON_NAME:yourdomain.comORGANIZATION:orgnameORGANIZATIONAL_UNIT:orgunitLOCALITY:AmsterdamPROVINCE:Noord-HollandCOUNTRY:NL## Specify where you want to store the outputCERT_OUTPUT:cert.crtCERT_CHAIN_OUTPUT:chain.crtPRIV_KEY_OUTPUT:priv.keyartifacts:paths:-cert.crt-chain.crt-priv.keyUsage with shell or SSH executorDefine a job that callsvenafi-vcert-request-certificate.Specify:Connection and authentication details for either a TPP or for Venafi as a Service.Certificate request parameters.Where to store the output.See the variables reference below.request_cert:script:-venafi-vcert-request-certificatevariables:## Specify TPP or Venafi as a Service parametersTPP_BASE_URL:https://my-tppTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.## Specify certificate parametersZONE_CONFIG_NAME:Certificates\\VCertCOMMON_NAME:yourdomain.comORGANIZATION:orgnameORGANIZATIONAL_UNIT:orgunitLOCALITY:AmsterdamPROVINCE:Noord-HollandCOUNTRY:NL## Specify where you want to store the outputCERT_OUTPUT:cert.crtCERT_CHAIN_OUTPUT:chain.crtPRIV_KEY_OUTPUT:priv.keyartifacts:paths:-cert.crt-chain.crt-priv.keyVariables: generalRequired (when using a TPP):TPP_BASE_URL: The TPP's base URL. It must not contain the/vedsdksuffix path.TPP_USERNAME: A login username for the TPP.TPP_PASSWORDorTPP_PASSWORD_BASE64: The password associated with the login username. You can specify it normally, or in Base64 format. The latter is useful for storing the password in a Gitlab variable, in masked form, because Gitlab can only mask variables whose content only consists of Base64 characters.Required (when using Venafi as a Service):VENAFI_AS_A_SERVICE_API_KEY: The Venafi as a Service API key.Required (no matter what you use):ZONE_CONFIG_NAME: the name of the zone configuration to use.When using Venafi as a Service, zone names are in the format ofapp name\api aliasOptional:EXPIRATION_WINDOW: number of hours before certificate expiry to request a new certificate. We'll check whether the certificate file referenced byCERT_OUTPUTalready exists, and if so, we'll only proceed with requesting a new certificate if the file's expiry date is withinEXPIRATION_WINDOWhours. Learn more atRenewing certificate only when expiration is near.KEY_TYPE: either 'RSA' (default) or 'ECDSA'.DNS_NAMES: a list of DNS names, as part of the certificate's Alternative Subject Names. Separate multiple values with a comma.Example:DNS_NAMES: host1.com,host2.comIP_ADDRESSES: a list of IP addresses, as part of the certificate's Alternative Subject Names. Separate multiple values with a comma.Example:IP_ADDRESSES: 127.0.0.1,127.0.0.2EMAIL_ADDRESSES: a list of email addresses, as part of the certificate's Alternative Subject Names. Separate multiple values with a comma.Example:EMAIL_ADDRESSES: a@a.com,b@b.comVariables: subject informationRequired:COMMON_NAME: the certificate's common name.Required or optional, depending on the connector's zone configuration:ORGANIZATIONORGANIZATIONAL_UNITLOCALITYPROVINCECOUNTRYVariables: outputRequired:PRIV_KEY_OUTPUT: a path to which the private key should be written.CERT_OUTPUT: a path to which the certificate should be written.CERT_CHAIN_OUTPUT: a path to which the certificate chain should be written.Download previous certificateDownloads a previously-requested certificate. This works by calling the Gitlab API, searching for a certificate in the latest successful CI build's artifacts. By default, we search in the CI builds of the same project and branch that the pipeline is running on.If the previous certificate is not found, then it exits with code 30.This operation is mainly meant to be used forrenewing certificate only when expiration is near. See the example in that section for further explanation of this operation's usage.Usage with Docker executorDefine a job that callsexec venafi-vcert-download-prev-cert.Note: theexeckeyword is required to ensure that the Gitlab job exits with the correct exit code.Ensure the job operates within the imagequay.io/venafi-gitlab-integration/tlsprotect-vcert. We recommend that you specify atagin order to avoid breaking changes introduced by new major versions.Ensure a failure due to exit code 30 is allowed.Ensure that the certificate to download, is also published as an artifact.Specify:The name of the CI job that's responsible for callingvenafi-vcert-request-certificate.The certificate's filename.See the variables reference below.download_prev_cert:image:quay.io/venafi-gitlab-integration/tlsprotect-vcertscript:-exec venafi-vcert-download-prev-certvariables:# Specify either one of the following. See the variables reference# for info and caveats.USE_CI_JOB_TOKEN:'true'# Or set GITLAB_BEARER_TOKEN from the UI, with masking enabled.REQUESTER_JOB_NAME:request_certCERT_FILENAME:cert.crtallow_failure:exit_codes:30artifacts:paths:-cert.crtUsage with shell or SSH executorDefine a job that callsexec venafi-vcert-download-prev-cert.Note: theexeckeyword is required to ensure that the Gitlab job exits with the correct exit code.Ensure a failure due to exit code 30 is allowed.Ensure that the certificate to download, is also published as an artifact.Specify:The name of the CI job that's responsible for callingvenafi-vcert-request-certificate.The certificate's filename.See the variables reference below.download_prev_cert:script:-exec venafi-vcert-download-prev-certvariables:# Specify either one of the following. See the variables reference# for info and caveats.USE_CI_JOB_TOKEN:'true'# Or set GITLAB_BEARER_TOKEN from the UI, with masking enabled.REQUESTER_JOB_NAME:request_certCERT_FILENAME:cert.crtallow_failure:exit_codes:30artifacts:paths:-cert.crtVariablesRequired: specify an authentication method. Either one of the following must be set:USE_CI_JOB_TOKEN: set to'true'to use theGitlab CI/CD job token, fetched from the predefined CI variableCI_JOB_TOKEN.Note: this requires Gitlab Premium >= 13.10.GITLAB_BEARER_TOKEN: set to a Personal/Project Access Token, or OAuth2 token.Required:REQUESTER_JOB_NAME: the name of the CI job that's responsible for callingvenafi-vcert-request-certificate. This operation will search inside that job's artifacts for the certificate.We expect that that job publishes the requested certificate as an artifact.CERT_FILENAME: the filename of the certificate to search for. This operation will attempt to download this file and store it in the workspace. Youmustalso publish this same file as an artifact.We expect that the job referenced byREQUESTER_JOB_NAME, publishes the requested certificate as an artifact under the specified filename.Optional:GITLAB_API_V4_URL: the base URL of the Gitlab API (version 4) to call. We request artifacts using this API. If not specified, we default to using the predefined CI variableCI_API_V4_URL.PROJECT_PATH: the name of the Gitlab project in which to search artifacts, e.g.myusername/myrepo. If not specified, we default to using the predefined CI variableCI_PROJECT_PATH.BRANCH_NAME: the name of the branch in which to search artifacts, e.g.main. If not specified, we default to using the predefined CI variableCI_COMMIT_REF_NAME.Renewing certificate only when expiration is nearNormally,venafi-vcert-request-certificaterequests a certificate every time it's called. Sometimes you only want to request a certificate when it's about to expire. TheEXPIRATION_WINDOWvariable addresses this use case.EXPIRATION_WINDOWexpects that you fetch the previously generated certificate, and store it under the same path as specified byCERT_OUTPUT. TheEXPIRATION_WINDOWfeature will then check whether that file's expiry date is withinEXPIRATION_WINDOWhours. If so, or if there is no previously generated certificate, then it'll proceed with requesting a new certificate. Otherwise it does nothing, and logs this decision.Here's an example of idiomatic usage.stages:-download_prev_cert-request_cert# Download previous certificate artifact.download_prev_cert:stage:download_prev_certimage:quay.io/venafi-gitlab-integration/tlsprotect-vcert:2-x86_64script:-exec venafi-vcert-download-prev-certvariables:# Specify either one of the following. See the variables reference# for info and caveats.USE_CI_JOB_TOKEN:'true'# Or set GITLAB_BEARER_TOKEN from the UI, with masking enabled.# The name of the job that's responsible for requesting a certificate.REQUESTER_JOB_NAME:request_cert# The filename of the certificate to download. This matches the# artifact filename as published by the `request_cert` job.CERT_FILENAME:cert.crtallow_failure:# If the certificate can't be found, the script exits with code 30.# We allow this failure so that `request_cert` will still be called,# just without a previous certificate.exit_codes:30artifacts:paths:# If a previous certificate is downloaded, publish it as an# artifact so that the `request_cert` job can consume it.-cert.crt# Only request a new certificate if there is no previous certificate,# or if the previous certificate expires within 48 hours.request_cert:image:quay.io/venafi-gitlab-integration/tlsprotect-vcert:2-x86_64script:-venafi-vcert-request-certificatevariables:TPP_BASE_URL:https://my-tppTPP_USERNAME:my_username# TPP_PASSWORD or TPP_PASSWORD_BASE64 should be set in the UI, with masking enabled.EXPIRATION_WINDOW:48ZONE_CONFIG_NAME:Certificates\\VCertCOMMON_NAME:yourdomain.comORGANIZATION:orgnameORGANIZATIONAL_UNIT:orgunitLOCALITY:AmsterdamPROVINCE:Noord-HollandCOUNTRY:NLCERT_OUTPUT:cert.crtCERT_CHAIN_OUTPUT:chain.crtPRIV_KEY_OUTPUT:priv.keyartifacts:paths:# Store the certificate file as an artifact. This file could# be a newly requested certificate, or it could be the previous# certificate. The next pipeline build will attempt to fetch this# file.-cert.crt-chain.crt-priv.key