Skip to main content
Version: 3.7.x

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 3.7.x 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 eventually be lost if Jenkins ever needs to be rebuilt from the ground up. 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 typeRequired AWS secret valueRequired tags
SSH username with private keyThe private key PEM in SecretStringjenkins:credentials:type=sshUserPrivateKey, jenkins:credentials:username=<username>
Username with passwordThe password in SecretStringjenkins:credentials:type=usernamePassword, jenkins:credentials:username=<username>
Secret textThe secret text in SecretStringjenkins:credentials:type=string

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​

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.

Create a secret in the AWS Management Console​

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.
  5. Remove the existing JSON example value and replace it with the desired credential value:
    • For an SSH private key credential, enter the private key file contents, including the dashed lines at the top and bottom.
    • For a username and password credential, enter the password.
    • For a secret text credential, enter the secret text.
  6. Choose Next.
  7. For Secret name, enter the desired Jenkins credential ID.
  8. For Description, enter a very short description. This is what Jenkins will show in drop-down boxes when you select credentials.
  9. In Tags, add the required Jenkins credential tags from Supported Credential Types.
    • For an SSH private key credential:
      • Set jenkins:credentials:type to sshUserPrivateKey.
      • Set the jenkins:credentials:username tag with the tag value set to the username (e.g., git for most Git SSH keys).
    • For a username and password credential:
      • Set jenkins:credentials:type to usernamePassword.
      • Set the jenkins:credentials:username tag with the tag value set to the username.
    • For a secret text credential:
      • Set jenkins:credentials:type to string.
  10. Choose Next.
  11. Keep automatic rotation disabled for this procedure, then choose Next.
  12. Review the secret details and choose Store.

Properly tagged credentials will quickly appear in the Jenkins credentials manager page, and be available for use.

Create a secret using the AWS CLI​

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

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

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 a secret text credential:

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

Properly tagged credentials will quickly appear in the Jenkins credentials manager page, and be available for use.

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​

In past releases you needed to set a volume map in your docker-compose.override.yml file to specify the value for the default Git credential. In release 3.6.x and higher bootstrap you can specify the key value by pointing at an AWS Secrets Manager secret. 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 file contents, including the dashed lines at the top and bottom.

  2. Ensure your bootstrap AWS user has permission to call secretsmanager:GetSecretValue for that secret. For more information, see Identity and Access Management (IAM) Permissions.

    • The bootstrap AWS user is controlled in your docker-compose.override.yml file by the field TF_VAR_aws_access_key_id.

  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.