Retrieving bundles using SCM

The CasC Bundle Retriever is a service that ensures Configuration as Code (CasC) bundles for the Operations center are always available and updated before the Operations center starts. The CasC Bundle Retriever is deployed alongside the Operations center container and allows you to manage its configuration via source control management (SCM) while ensuring that the latest bundle version is always locally available during both initialization and while running.

If you are using GitHub as your SCM, you can configure the CasC Bundle Retriever to use webhooks. When a push is made to the branch where the bundle is located, GitHub sends the push event to the CasC Bundle Retriever, that checks out the bundle and notifies CloudBees CI that a new version is available.

Bundle retrieval process

The CasC Bundle Retriever consists of two additional containers that run in the same Kubernetes pod as the Operations center. The first is an init container that executes before the Operations center container is initialized and checks out the CasC bundle from SCM, ensuring that it is available on disk before the Operations center starts. The second is a sidecar container that is responsible for ensuring that the CasC bundle updates are made available to the Operations center.

The following diagrams illustrate the bundle retreival process.

Init container

Figure 1. Bundle retrieval - Init container

Init container queries the SCM to retrieve the bundle.
SCM returns the bundle.
Init container writes the bundle to the location where the Operations center looks for it on startup.
Operations center reads the bundle and starts.

Sidecar container

Figure 2. Bundle retrieval - Sidecar container

CasC Bundle retriever periodically queries the SCM for any bundle updates.
CasC Bundle Retriever checks out the bundle from the SCM if a new version is found.
Bundle is stored in the Operations center bundle location.
Bundle retriever notifies the Operations center that a new bundle is available.

CasC Bundle Retriever integration with Bundle Update Timing

The CasC Bundle Retriever checks out a new bundle version and makes it available for the Operations center. However, making the new bundle available does not mean the bundle is applied to the instance. The user still needs to manually apply the new bundle version to the instance and then either reload the configuration or restart the instance.

In a GitOps workflow, this manual step is not desired. Users would prefer to merge changes in the repository containing the bundle, have those changes checked out automatically, and apply the new bundle version without any user intervention. This can be accomplished through the Bundle Update Timing feature. With Bundle Update Timing, the instance can be configured to automatically apply the new bundle (via reload or restart) when changes are detected. In this scenario, when the CasC Bundle Retriever checks out the new bundle version and notifies the Operations center that an update is available. The instance then determines if the configuration can be updated automatically, and if that is not possible, a safe restart is scheduled. This allows new bundle versions to be applied without user intervention.

To configure Bundle Update Timing refer to Bundle update timing for the operations center.

Prerequisites

At minimum, the CasC Bundle Retriever requires the following:

A SCM repository containing a CasC bundle for the Operations center
Kubernetes 1.25 or higher
The ability to create Kubernetes secrets
The ability to install or upgrade CloudBees CI on modern cloud platforms in Kubernetes using Helm

Additionally, you can extend the functionality of the CasC Bundle Retriever by enabling:

CloudBees CI notifications
GitHub Webhooks notifications
Email notifications of bundle updates

Configuration and installation

The CasC Bundle Retriever is included with the CloudBees CI Modern Helm charts and can be managed in the same manner. Enabling the CasC Bundle Retriever requires passing additional values when performing a helm install or helm upgrade and optionally creating any secrets that are needed for your configuration.

Some features and functionality also require the configuration of Kubernetes secrets. These secrets should be created prior to enabling the CasC Bundle Retriever if you intend to enable the functionality that depends on them.

By default, the bundle retriever searches for the secrets it needs in the casc-retriever-secrets object. You can change the name of this object, as well as the keys associated with each secret within Kubernetes by passing additional values when performing a helm install or helm upgrade.

The following sections detail the configuration and secrets needed to enable each feature. Configuration values may be passed as part of a values.yaml file or individually using --set XXX=yyy arguments to the helm command.

Enable the CasC Bundle Retriever

The CasC Bundle Retriever is part of the overall CasC feature. To use it you must enable both CasC and the CascRetriever

Helm arguments example

--set OperationsCenter.CasC.Enabled=true
--set OperationsCenter.CasC.Retriever.Enabled=true▼

A values.yaml example

OperationsCenter:
  CasC:
    Enabled: true (1)
    Retriever:
      Enabled: true (2)
      scmRepo: "<https://github.com/xxxxxxxxx/xxxxx.git>" (3)
      scmBundlePath: "oc-casc-bundle" (4)
      scmBranch: "main" (5)▼

1	Set value to `true` to enable `CasC`.
2	Set value to `true` to enable the retriever.
3	Enter the the URL of the repository containing the bundle.
4	Enter the path to a folder in the repository where the `bundle.yaml` file is located.
5	Enter the branch of the repository containing the bundle.

SCM Configuration

The following values can be used to configure access to the SCM that contains your CasC bundle. All values must be nested under OperationsCenter.CasC.Retriever. For readability only the subvalue name is shown in the table below.

Parameter Description Default Value Required/Optional

scmRepo

The URL of the repository containing the CasC bundle. When using ssh for authentication, the URL must have the format ssh://[user@]server/path/of/repo.git.

Required

It is strongly recommended that git:// is not used in the URL format.

scmBranch

The branch of the repository containing the CasC bundle.

Required

scmBundlePath

Path to a folder in the repository where the bundle.yaml file is located.

Optional

Do not start the bundle path with a forward slash (/) otherwise it returns an error.

scmPollingInterval

How frequently to poll SCM for changes, specified using the standard Java Duration format.

PT20M

Optional

ocBundleAutomaticVersion

If set to true, the commit hash will replace the version of the bundle from the SCM.

false

Optional

githubWebhooksEnabled

Enable or disable support for GitHub Webhooks.

true

Optional

emailBundleUpdateActive

Enables email notifications of new bundles.

false

Optional

emailUpdateSubject

If using email notifications, the subject of the email.

Optional

emailBundleUpdateBody

If using email notifications, the body of the email.

Optional

emailBundleUpdateList

If using email notifications, the comma-separated "to" (recipients) list of email addresses.

Optional

smtpAuthMethods

If using email notifications, SMTP authentication methods, one or more from DIGEST-MD5, CRAM-SHA256, CRAM-SHA1, CRAM-MD5, or PLAIN login.

Optional

emailBundleUpdateFrom

If using email notifications, the sender’s email address.

Optional

smtpHost

If using email notifications, hostname of the SMTP server.

Optional

smtpPort

If using email notifications, port of the SMTP server.

Optional

smtpStartTls

If using email notifications, usage of Transport Layer Security. Possible values are REQUIRED or OPTIONAL.

Optional

secrets.secretName

Define the name of the Kubernetes object that holds the secrets used by the CasC Bundle Retriever.

casc-retriever-secrets

Optional

secrets.scmUsername

The name of the key that refers to the SCM username in the application secrets.

Optional

secrets.scmPassword

SCM password or token used in user authentication in the repository.

Optional

secrets.sshConfig

The name of the Kubernetes secret object containing the SSH credentials to use when authenticating with the SCM. If this secret is provided, it is mounted as a volume to use with the SSH authentication on SCM.

Optional

secrets.githubWebhookSecret

The name of the key that refers to the GitHub Webhooks secret. If a GitHub Webhooks secret is not supplied, all webhooks from the configured repository and branch will be accepted.

Optional

secrets.smtpUsername

If using email notifications, the username to use when authenticating with the SMTP server. If no username is present, the application will fallback to SSH authentication.

Optional

secrets.smtpPassword

If using email notifications, the password to use when authenticating with the SMTP server.

Optional

Basic configuration

The only required configuration consists of the SCM repository and branch to fetch the CasC bundle. Optionally, you can configure a custom polling interval, as well as specify a path within the repository where the CasC bundle is located. The latter can be useful if you have multiple bundles in a single repository/branch and want to select from among them.

Helm arguments example

--set OperationsCenter.CasC.Enabled=true
--set OperationsCenter.CasC.Retriever.Enabled=true
--set OperationsCenter.CasC.Retriever.scmRepo="<ssh://user@server/path/of/repo.git>"
--set OperationsCenter.CasC.Retriever.scmBranch="<scm branch>"
--set OperationsCenter.CasC.Retriever.scmBundlePath="<repository path of bundle.yaml>"
--set OperationsCenter.CasC.Retriever.scmPollingInterval="PT20M"▼

A values.yaml example

OperationsCenter:
  CasC:
    Enabled: true
    Retriever:
      Enabled: true
      scmRepo: <ssh://user@server/path/of/repo.git>
      scmBranch: <scm branch>
      scmBundlePath: <repository path of bundle.yaml>
      scmPollingInterval: PT20M▼

Configuring SSH authentication for SCM

To use SSH authentication, you need to create a Kubernetes secret containing the private key that will be used to authenticate with SCM. You also need to provide the name associated with this secret when configuring the CasC bundle so that it can be mounted inside the container.

Use the kubectl command to create this secret from an existing SSH configuration (typically found in the ~/.ssh). The following example creates a secret called my-ssh-config using an existing SSH configuration:

kubectl create secret generic my-ssh-config --from-file=id_rsa=/path/to/.ssh/id_rsa --from-file=config=/path/to/.ssh/config --from-file=known_hosts=/path/to/.ssh/known_hosts▼

SSH keys must be in OpenSSH format.

To use this secret to authenticate with SCM, you must tell the CasC Bundle Retriever the name of the object which holds the secrets. This can be done by setting the value of OperationsCenter.CasC.Retriever.secrets.sshConfig to the name of the object containing the secret when installing or upgrading your deployment using Helm.

Helm arguments example

--set OperationsCenter.CasC.Enabled=true
--set OperationsCenter.CasC.Retriever.Enabled=true
--set OperationsCenter.CasC.Retriever.scmRepo="<ssh://user@server/path/of/repo.git>"
--set OperationsCenter.CasC.Retriever.scmBranch="<scm branch>"
--set OperationsCenter.CasC.Retriever.scmBundlePath="<repository path of bundle.yaml>"
--set OperationsCenter.CasC.Retriever.scmPollingInterval="PT20M"
--set OperationsCenter.CasC.Retriever.secrets.sshConfig="my-ssh-config"▼

A values.yaml example

OperationsCenter:
  CasC:
    Enabled: true
    Retriever:
      Enabled: true
      scmRepo: <ssh://[user@]server/path/of/repo.git>
      scmBranch: <scm branch>
      scmBundlePath: <repository path of bundle.yaml>
      scmPollingInterval: PT20M
      secrets:
        sshConfig: my-ssh-config▼

Configuring Username/Password authentication for SCM

To use username and password authentication for SCM, you must add values for the SCM username and password to the Kubernetes secret object used by the CasC Bundle Retriever. You also need to set the key associated with each secret value when installing or upgrading your deployment using Helm.

Helm arguments example

--set OperationsCenter.CasC.Enabled=true
--set OperationsCenter.CasC.Retriever.Enabled=true
--set OperationsCenter.CasC.Retriever.scmRepo="<ssh://[user@]server/path/of/repo.git>"
--set OperationsCenter.CasC.Retriever.scmBranch="<scm branch>"
--set OperationsCenter.CasC.Retriever.scmBundlePath="<repository path of bundle.yaml>"
--set OperationsCenter.CasC.Retriever.scmPollingInterval="PT20M"
--set OperationsCenter.CasC.Retriever.secrets.scmUsername=<scm username key>
--set OperationsCenter.CasC.Retriever.secrets.scmPassword=<scm password key>▼

A values.yaml example

OperationsCenter:
  CasC:
    Enabled: true
    Retriever:
      Enabled: true
      scmRepo: <ssh://user@server/path/of/repo.git>
      scmBranch: <scm branch>
      scmBundlePath: <repository path of bundle.yaml>
      scmPollingInterval: PT20M
      secrets:
        scmUsername: <scm username key>
        scmPassword: <scm password key>▼

A secrets.yaml example

apiVersion: v1
kind: Secret
metadata:
  name: casc-retriever-secrets
type: Opaque
stringData:
  <scm username key>: <scm username>
  <scm password key>: <scm password>▼

(Optional) Configure GitHub webhook support

The CasC Bundle Retriever supports receiving webhook events from GitHub, enabling real-time updates when the CasC bundle is changed. The webhook endpoint can optionally be secured through the use of a shared secret. The CasC Bundle Retriever exposes the incoming webhook endpoint at https://<cjoc hostname>/casc-retriever/retriever-github-webhook/. This value should be used for the Payload URL when configuring your GitHub repository to support sending webhook events. For more information, refer to the GitHub Webhooks official documentation.

GitHub Webhooks are enabled by default. If you do not intend to use this functionality, it is strongly recommended you disable this feature by setting OperationsCenter.CasC.Retriever.githubWebhooksEnabled=false when configuring your deployment.
It is strongly recommended to use a shared secret if you are using GitHub Webhooks. If left empty, the CasC Bundle Retriever will accept incoming requests from any client.

Helm arguments example

--set OperationsCenter.CasC.Enabled=true
--set OperationsCenter.CasC.Retriever.Enabled=true
--set OperationsCenter.CasC.Retriever.githubWebhooksEnabled=true
--set OperationsCenter.CasC.Retriever.secrets.githubWebhookSecret=<github webhook secret key>▼

A values.yaml example

OperationsCenter:
  CasC:
    Enabled: true
    Retriever:
      Enabled: true
      githubWebhooksEnabled: true
      secrets:
        githubWebhookSecret: <github webhook secret key>▼

A secrets.yaml example

apiVersion: v1
kind: Secret
metadata:
  name: casc-retriever-secrets
type: Opaque
stringData:
  <github webhook secret key>: <github webhook secret>▼

Enabling optional support for GitHub Webhooks requires the use of Github as your SCM.

(Optional) Enable email notifcations of CasC bundle updates

Email notifications can be sent when a new bundle is detected. Email messages can have custom FROM, BODY, and SUBJECT fields.

Helm arguments example

--set OperationsCenter.CasC.Enabled=true
--set OperationsCenter.CasC.Retriever.Enabled=true
--set OperationsCenter.CasC.Retriever.emailBundleUpdateActive=true
--set OperationsCenter.CasC.Retriever.emailUpdateSubject="<email subject line>"
--set OperationsCenter.CasC.Retriever.emailBundleUpdateBody="<email body>"
--set OperationsCenter.CasC.Retriever.emailBundleUpdateFrom="<from email>"
--set OperationsCenter.CasC.Retriever.emailBundleUpdateList="<email1,email2,email3...>"
--set OperationsCenter.CasC.Retriever.smtpHost="<smtp hostname>"
--set OperationsCenter.CasC.Retriever.smtpPort="<smtp port>"
--set OperationsCenter.CasC.Retriever.smtpAuthMethods="<DIGEST-MD5 || CRAM-SHA256 || CRAM-SHA1 || CRAM-MD5 || PLAIN || LOGIN>"
--set OperationsCenter.CasC.Retriever.smtpStartTls="<REQUIRED || OPTIONAL>"
--set OperationsCenter.CasC.Retriever.secrets.smtpUsername=<smtp username secret key>
--set OperationsCenter.CasC.Retriever.secrets.smtpUsername=<smtp password secret key>▼

A values.yaml example

OperationsCenter:
  CasC:
    Enabled: true
    Retriever:
      Enabled: true
      emailBundleUpdateActive: true
      emailUpdateSubject: <email subject line>
      emailBundleUpdateBody: <email body>
      emailBundleUpdateFrom: <from email>
      emailBundleUpdateList: <email1,email2,email3...>
      smtpHost: <smtp hostname>
      smtpPort: <smtp port>
      smtpAuthMethods: <DIGEST-MD5 || CRAM-SHA256 || CRAM-SHA1 || CRAM-MD5 || PLAIN || LOGIN>
      smtpStartTls:<REQUIRED || OPTIONAL>
      secrets:
        smtpUsername: <smtp username secret key>
        smtpPassword: <smtp password secret key>▼

A secrets.yaml example

apiVersion: v1
kind: Secret
metadata:
  name: casc-retriever-secrets
type: Opaque
stringData:
  <smtp username secret key>: <smtp username>
  <smtp password secret key>: <smtp password>▼

Installation

After determining your configuration details, use the Helm charts to install the bundle retriever into a new cluster or an existing cluster. It is recomended to create any needed secrets before beginning the installation or upgrade.

Install CasC Bundle Retriever on a new cluster

To install the bundle retriever in a new cluster:

Follow the installation instructions on Kubernetes for CloudBees CI on modern cloud platforms.
Make sure the Kubernetes secrets needed for your chosen configuration exist before starting the Helm installation process.
Pass the configuration values of your chosen configuration by doing one of the following:
- Pass the needed configuration values to helm install using a values.yaml file.
  
  Your specific configuration may include values not shown in the example below.
  OperationsCenter: CasC: Enabled: true Retriever: Enabled: true scmRepo: "https://github.com/miketest/casc-scm-demo" scmBranch: "main"
  ▼
- Execute the helm install command by setting each value individually using the -set name=value command as shown in the example below.
  $ helm install -set name=value
  ▼

Install the CasC Bundle Retriever on an existing cluster

To install the bundle retriever on an existing cluster:

Follow the upgrade instructions using Helm charts for CloudBees CI on modern cloud platforms.
Ensure the Kubernetes secrets needed for your chosen configuration exist before starting the Helm installation process.
Pass the configuration values of your chosen configuration by doing one of the following:
- Pass the needed configuration values to helm install using a values.yaml file.
  
  Your specific configuration may include values not shown in the example below.
  OperationsCenter: CasC: Enabled: true Retriever: Enabled: true scmRepo: "https://github.com/miketest/casc-scm-demo" scmBranch: "main"
  ▼
- Execute the helm install command by setting each value individually and using the -set name=value command as shown in the example below.
  $ helm install -set name=value
  ▼