IBM Cloud Docs
Creating a Code Engine job

Creating a Code Engine job

The custom credentials secret type allows Secrets Manager users to manage the lifecycle of credentials for external systems (for example, Artifactory, PagerDuty) using Secrets Manager APIs and integrations. To create custom credentials secrets, you must first set up an IBM Cloud® Code Engine project and define a Code Engine job to interface between Secrets Manager and the external service requiring credentials.

Custom credentials support a wide range of third-party systems, so guidance for configuring your Code Engine job is intentionally general, focusing on Code Engine best practices. If your parameters are correctly formatted and you select a valid Code Engine project and job, Secrets Manager can run the job with various configurations. However, Secrets Manager does not validate whether your configuration aligns with your specific use case. It only runs the provided setup.

To assist with implementing job logic for interacting with external providers, Secrets Manager offers developer documentation, best practices, job generator and deployer tools, and code examples. Learn how to design a new credentials provider job in the Custom Credentials Providers repository.

Credentials provider job lifecycle

A typical job flow involves:

  1. Creating the credentials, where new credentials are generated.
  2. Deleting the credentials, where credentials are revoked.
  3. Updating the secret task, which sends the result back to Secrets Manager.

The following Code Engine job flow diagram illustrates this lifecycle.

The diagram shows the lifecycle of a Code Engine credentials provider job.
Code Engine job lifecycle

Secrets Manager retries daily (for up to 10 days) to delete credentials after a failed deletion attempt. Request retries are recommended when applicable but omitted in the flow diagram for clarity. A 400 or 404 status response to the Secret task update request indicates that the secret task cannot be updated by a retry.

Security considerations

To enhance security:

  • Follow the principle of least privilege: restrict job access to only the necessary secrets by using a dedicated secret group.
  • IAM roles: assign the API key used by the job to authenticate with Secrets Manager the SecretTaskUpdater role. If the job needs to read secrets, also assign the SecretsReader role. Both roles should be scoped to the dedicated secret group.
  • Avoid personally identifiable information (PII) and confidential data: do not use personal identifiers or confidential data (such as email addresses or social security numbers) as input parameters or as credential IDs. Secrets Manager treats the input parameters and credential ID as metadata, not as sensitive secret data.

Error handling

If the credentials provider job is unable to create or delete the credentials, it should update Secrets Manager with an application error code and a user facing error message. This error is displayed in the Secrets Manager console for the failed task and allow the user to apply a corrective action.

Troubleshooting

By default, Secrets Manager configures Code Engine to immediately remove completed jobs. This prevents job run accumulation and helps avoid exceeding quota limits over time. However, during development, you may want to retain completed jobs to review their configuration and logs.

To retain completed jobs using the Code Engine UI:

  1. In the IBM Cloud Console, navigate to Containers → Projects, and open your credentials provider project.
  2. Within the project page, go to Jobs, click the Jobs tab, and select your job.
  3. In the Configuration page, open the Environment variables tab.
  4. Locate the CE_REMOVE_COMPLETED_JOBS variable and click on its row to edit.
  5. In the Edit environment variable panel, change the value from IMMEDIATELY to 3d, then click Done.
  6. Return to the Environment variables page and click Deploy (top right) to apply the changes. Completed job runs will now be retained for 3 days.

For troubleshooting jobs in a production environment, it is recommended to integrate Code Engine with Cloud Logs. Refer to the documentation of both services for setup instructions.

Next steps

After you have created your Code Engine project and job, you can now move on to creating a custom credentials engine configuration.