Basic template requirements

Every template has the following set of basic requirements:

• An apiVersion field with a value of v1

• A kind field with a value of Pod

• A metadata field to uniquely identify the pod with the following data:

  • A name field with a value equal to '{{NAME}}'

  • A labels field defining the following key and value pair that will be used as the resource label to identify resources it creates and manages in your cluster:

    '{{RESOURCE_LABEL}}': <VALUE>

    Replace <VALUE> with the resource label name you want Bamboo to use to identify resources in your Kubernetes cluster.

• A spec field defining the properties of exactly one ephemeral agent container under containers:

  • An image field declaring the Docker image to use. This can be a custom image or the base Docker image:

    atlassian/bamboo-agent-base:<YOUR_BAMBOO_VERSION>

Replace <YOUR_BAMBOO_VERSION> with the Bamboo version number that you’re currently running. For example: atlassian/bamboo-agent-base:9.3.0

• • A name field with a value equal to '{{BAMBOO_AGENT_CONTAINER_NAME}}'

  • An env field containing the BAMBOO_EPHEMERAL_AGENT_DATA environment variable with a string value equal to '{{BAMBOO_EPHEMERAL_AGENT_DATA_VAL}}'

• A restartPolicy field with a value of Never

Here’s an example YAML configuration that you can use as the starting point for creating your own ephemeral agent template:

---
apiVersion: v1
kind: Pod
metadata:
  name: '{{NAME}}'
  labels:
      '{{RESOURCE_LABEL}}': <VALUE>
spec:
  containers:
    - image: atlassian/bamboo-agent-base:<YOUR_BAMBOO_VERSION>
      name: '{{BAMBOO_AGENT_CONTAINER_NAME}}'
      env:
        - name: BAMBOO_EPHEMERAL_AGENT_DATA
          value: '{{BAMBOO_EPHEMERAL_AGENT_DATA_VAL}}'
  restartPolicy: Never

Creating custom images

The base Docker image used in the example YAML configuration above contains only a minimal setup to run a basic ephemeral agent, which may not have sufficient capabilities to run your builds. If you need additional capabilities beyond what the basic image provides, you can extend the image as needed.

To extend the basic image:

1. Create a new Docker file that defines all the capabilities that you want your ephemeral agent to have. In the following example, we’ll install Maven:

   FROM atlassian/bamboo-agent-base:<YOUR_BAMBOO_VERSION>
   RUN apt-get update && \
       apt-get install maven -y

   Replace <YOUR_BAMBOO_VERSION> with the Bamboo version number that you’re currently running.

2. Build the new image:

   docker build --tag <MY_IMAGE_TAG>

   For example:

   docker build --tag my-agent-with-maven-image

3. Create a new template or modify an existing one to use the new image.

4. Add all the capabilities you need to the template.
   In our Maven example above, the configuration may look like this:

   Field	Value
   Capability type	Executable
   Type	Maven 3.x
   Path	/usr/share/maven

You can now use your customized template to run builds and deployments.

Adding multiple containers to a template

Apart from the Bamboo ephemeral agent container, your template can define other containers that the ephemeral agent can communicate with to exchange data or run other processes.

To add multiple containers, define each one as an entry in the containers list.

In the following example, we’ll add extra containers for the PostgreSQL database and nginx server:

---
apiVersion: v1
kind: Pod
metadata:
  name: '{{NAME}}'
  labels:
      '{{RESOURCE_LABEL}}': <VALUE>
spec:
  containers:
    - image: atlassian/bamboo-agent-base:<YOUR_BAMBOO_VERSION>
      name: '{{BAMBOO_AGENT_CONTAINER_NAME}}'
      env:
        - name: BAMBOO_EPHEMERAL_AGENT_DATA
          value: '{{BAMBOO_EPHEMERAL_AGENT_DATA_VAL}}'
    - image: postgres:latest
      name: postgres-db
      env:
        - name: POSTGRES_PASSWORD
          value: password
    - image: nginx:latest
      name: nginx-sever
  restartPolicy: Never

Delaying the start of the ephemeral agent container

If you’re going to be running pods with multiple containers in them, it may happen that you’ll want to delay the start of the ephemeral agent container until the other containers are successfully up and running.

To delay the start of the ephemeral agent container:

1. In the .spec.volumes, define an emptyDir volume, where your additional containers will report their readiness.

2. In the ephemeral agent container configuration section, under volumeMounts, declare a read-only mount point for the previously defined emptyDir volume by specifying a name and mountPath.

3. In each extra container, under .spec.containers[*].volumeMounts, declare a writeable mount point for the previously added emptyDir volume by specifying the name, mountPath, and readonly: false properties.

4. To each extra container, under .spec.containers[*], add a postStart lifecycle hook that will execute a command to create a unique file in the mounted volume’s file system. For example:

   lifecycle:
     postStart:
       exec:
         command: ['/bin/sh', '-c', 'touch /registration/nginx']

5. In the ephemeral agent container configuration section, declare the following environment variables as key-value pair entries into the env list:

   • KUBE_NUM_EXTRA_CONTAINERS equal to the number of containers the agent should wait for

   • EXTRA_CONTAINERS_REGISTRATION_DIRECTORY equal to the registration directory mountPath

For example:

---
apiVersion: v1
kind: Pod
metadata:
  name: '{{NAME}}'
  labels:
    '{{RESOURCE_LABEL}}': <VALUE>
spec:
  volumes:
    -   name: registration-volume
        emptyDir: {}
  containers:
    -   image: atlassian/bamboo-agent-base:<YOUR_BAMBOO_VERSION>
        name: '{{BAMBOO_AGENT_CONTAINER_NAME}}'
        volumeMounts:
          -   name: registration-volume
              mountPath: /registration
        env:
          -   name: BAMBOO_EPHEMERAL_AGENT_DATA
              value: '{{BAMBOO_EPHEMERAL_AGENT_DATA_VAL}}'
          -   name: KUBE_NUM_EXTRA_CONTAINERS
              value: '1'
          -   name: EXTRA_CONTAINERS_REGISTRATION_DIRECTORY
              value: /registration
    -   image: nginx:latest
        name: nginx-sever
        volumeMounts:
          -   name: registration-volume
              mountPath: /registration
              readOnly: false
        lifecycle:
           postStart:
              exec:
                 command: ['/bin/sh', '-c', 'touch /registration/nginx']
  restartPolicy: Never

Reducing server resource usage on ephemeral agent startup

When an ephemeral agent starts up, it fetches the files it needs to perform a build or deployment from the Bamboo server. Fetching these files on every ephemeral agent startup may put your Bamboo server under additional load and increase the ephemeral agent's overall startup time.

You can offload some of the agent's files to a persistent volume in your Kubernetes cluster to speed up the launch of ephemeral agents and make sure that your Bamboo server's resources are put to good use.

Related pages

• Page:
  Configuring an ephemeral agent template’s capabilities
• Page:
  Creating ephemeral agent templates
• Page:
  Editing an ephemeral agent template
• Page:
  Enabling and disabling ephemeral agent templates
• Page:
  Ephemeral agent template management
• Page:
  Viewing ephemeral agent template details