Manage Jenkins Credentials

You may occasionally need to add additional credentials to Jenkins. In the past, teams added credentials manually in the Jenkins web interface. The recommended way is now via the AWS Secrets Manager integration described in this page. This capability is included out-of-the-box in CloudOps for Kubernetes release 4.0 and higher. If you add custom Jenkins credentials this way then those credentials will always be available.

Credentials that you may have added manually might be removed when Jenkins is reconfigured from code. We recommend that you replace any manually added credentials using this new approach.

note

For more information about the Jenkins integration, see the AWS Secrets Manager Credentials Provider plugin and the plugin documentation.

Supported Credential Types

The AWS Secrets Manager credentials provider supports the following Jenkins credential types in CloudOps for Kubernetes:

Jenkins credential type	Required AWS secret value	Required tags
Secret text	The secret text in SecretString	jenkins:credentials:type=string
Username with password	The password in SecretString	jenkins:credentials:type=usernamePassword, jenkins:credentials:username=<username>
SSH username with private key	The private key PEM in SecretString	jenkins:credentials:type=sshUserPrivateKey, jenkins:credentials:username=<username>

The Secrets Manager secret name becomes the Jenkins credential ID. For example, a secret named ep-commerce-git-ssh is available in Jenkins as a credential with ID ep-commerce-git-ssh.

note

Use credential IDs that contain only letters, numbers, underscores, periods, and hyphens. Avoid spaces and special characters.

Add a Jenkins Credential in AWS Secrets Manager

1. Choose the name for the credential. The name will be both the AWS Secrets Manager secret name and the Jenkins credential ID.
2. Create the secret in the same AWS account and AWS Region as the CloudOps for Kubernetes cluster.
3. Store the credential value in the secret string:
   • For a secret text credential, store the secret text.
   • For a username and password credential, store the password.
   • For an SSH private key credential, store the private key PEM.
4. Add the required Jenkins credential tags to the secret.
5. Add any tags required by your organization, such as owner, environment, cost center, or rotation policy.
6. Wait for Jenkins to discover the secret, or restart Jenkins if you need the credential immediately.
7. Use the secret name as the credential ID in Jenkins job parameters.

You can create the secret in the AWS Management Console or with the AWS CLI. For the complete AWS procedure, see Create an AWS Secrets Manager secret.

To create the secret in the AWS Management Console:

1. Open the AWS Secrets Manager console in the same AWS Region as the CloudOps for Kubernetes cluster.
2. Choose Store a new secret.
3. For Secret type, choose Other type of secret.
4. In Key/value pairs, choose the Plaintext tab and enter the credential value:
   • For a secret text credential, enter the secret text.
   • For a username and password credential, enter the password. Add the username as the jenkins:credentials:username tag.
   • For an SSH private key credential, enter the private key PEM. Add the username as the jenkins:credentials:username tag.
5. Choose Next.
6. For Secret name, enter the Jenkins credential ID.
7. In Tags, add the required Jenkins credential tags from Supported Credential Types.
8. Choose Next.
9. Keep automatic rotation disabled for this procedure, then choose Next.
10. Review the secret details and choose Store.

The following examples show the AWS CLI commands for creating the supported secret types.

Create a secret text credential:

aws secretsmanager create-secret \
  --name my-secret-text \
  --secret-string "secret value" \
  --tags Key=jenkins:credentials:type,Value=string

Create a username with password credential:

aws secretsmanager create-secret \
  --name my-username-password \
  --secret-string "password value" \
  --tags \
    Key=jenkins:credentials:type,Value=usernamePassword \
    Key=jenkins:credentials:username,Value=my-user

Create an SSH username with private key credential:

aws secretsmanager create-secret \
  --name my-git-ssh-key \
  --secret-string file://./id_rsa \
  --tags \
    Key=jenkins:credentials:type,Value=sshUserPrivateKey \
    Key=jenkins:credentials:username,Value=git

Use a Secrets Manager Credential in Jenkins Jobs

After Jenkins discovers a Secrets Manager credential, use the AWS secret name anywhere a Jenkins credential ID is requested.

Examples of job parameters that can use Secrets Manager credential IDs include:

• epCommerceCredentialId
• dockerCredentialId
• EP_COMMERCE_CONFIG_SSH_KEY
• EP_COMMERCE_CONFIG_GPG_KEY

Switch the Default Git Credential to Secrets Manager

The bootstrap process can read the Git SSH private key from AWS Secrets Manager instead of from a mounted file on the operations workstation. Switching to Secrets Manager is optional and recommended when you want the bootstrap Git credential to be managed in AWS.

1. Create an AWS Secrets Manager secret containing the Git SSH private key PEM.

2. Ensure the Identity and Access Management (IAM) user for the access key specified by TF_VAR_aws_access_key_id and TF_VAR_aws_secret_access_key in docker-compose.override.yml can call secretsmanager:GetSecretValue for that secret. For more information, see IAM Permissions.

3. Set the following variables in docker-compose.override.yml:

   TF_VAR_bootstrap_mode: "setup"
   TF_VAR_git_credential_secret_arn: "<secret-arn>"
   

4. Remove the local Git SSH private key volume mount if it is no longer needed.

5. From the operations workstation, run docker-compose up.

When TF_VAR_git_credential_secret_arn is set, the bootstrap container downloads the private key from Secrets Manager and uses it as the Git SSH credential for the bootstrap run.

Back Up Existing Jenkins Credentials to Secrets Manager

CloudOps for Kubernetes includes the backup-jenkins-credentials-to-sm Jenkins job. This job is a safety net to back up any manually added credentials. When it runs, the job finds any supported manually added credentials and backs them up to Secrets Manager secrets. These backups are available in Secrets Manager in case the manually added credentials are lost. These backups do not get automatically restored to Jenkins.

The backup job:

• Finds Jenkins-local system credentials.
• Checks if the credential has previously been backed up as backup-<credentialId>. If it has, then it skips backing up that credential.
• Creates backup secrets named backup-<credentialId>.
• Adds backup metadata tags such as backup:credential:type, backup:credential:id, and backup:credential:username.
• Archives a jenkins-credentials-backup-report.md artifact with the result for each credential.

important

The backup job creates backup copies. It does not automatically update Jenkins job parameters or delete Jenkins-local credentials.