README.md

container-agent

For deploying a CircleCI Container Agent

Support

Support for the CircleCI Self-Hosted Runner helm chart can be found on the CircleCI support page. There docs, support articles, and community support threads may be reviewed as well as support tickets raised.

Feature requests for the CircleCI Self-Hosted Runner helm chart can be raised and voted on via the CircleCI Canny board

Installation

Requirements

Kubernetes: >= 1.25-0

Helm: 3.x

Installing the Chart

To install the chart with the release name container-agent:

• Run helm repo add container-agent https://packagecloud.io/circleci/container-agent/helm
• Run helm repo update
• Run helm install container-agent container-agent/container-agent -n circleci to install the chart
• Update the values.yaml file with your resource class token in the tokens key under the agent key

This will deploy the container runner to the Kubernetes cluster as a release called container-agent. You can view the default values by running helm show values circleci/container-agent and override these using the --values or --set name=value flags on the install command below. The Helm Chart Parameters sections list the parameters that can be configured during installation.

Update values.yaml

To run a job with no custom configuration, add the following configuration to the Helm chart values.yaml. MY_TOKEN is your runner resource class token. Update namespace/my-rc with your namespace and runner resource class.

agent:
  resourceClasses:
    namespace/my-rc:
      token: MY_TOKEN

To learn more about setting up Container Runner, read our docs

Uninstalling the Chart

To uninstall the container-agent deployment:

$ helm uninstall container-agent

The command removes all the Kubernetes objects associated with the chart and deletes the release

Values

Key	Type	Default	Description
agent.affinity	object	{}	Agent affinity and anti-affinity Ref: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity
agent.autodetectPlatform	bool	true	Toggle autodetection of OS and CPU architecture to request the appropriate task-agent binary in a heterogeneous cluster. If toggled on, this requires container-agent to have certain cluster-wide permissions for nodes. If toggled off, the cluster is assumed to be homogeneous and the OS and architecture of container-agent are used.
agent.constraintChecker.enable	bool	false	Enable constraint checking (This requires at least List Node permissions)
agent.constraintChecker.interval	string	"15m"	Check interval
agent.constraintChecker.threshold	int	3	Number of failed checks before disabling task claim
agent.containerSecurityContext	object	{}	Security Context policies for agent containers
agent.customSecret	string	""	Name of the user provided secret containing resource class tokens. You can mix tokens from this secret and in the secret created from tokens specified in the resourceClasses section below Ref: https://circleci.com/docs/container-runner/#custom-secret The tokens should be specified as secret key-value pairs of the form ResourceClass: Token The resource class name needs to match the names configured below exactly to match tokens to the correct configuration As Kubernetes does not allow / in secret keys, a period (.) should be substituted instead
agent.environment	object	{}	A dictionary of key-value pairs to set as environment variables in the container-agent app container. Note that this does not set environment variables in a task, which can be done via agent.resourceClasses or in CircleCI.
agent.forceUpdate	bool	false	Force a rolling update of the agent deployment
agent.gc.enabled	bool	true	Enable garbage collection (GC) of Kubernetes objects such as Pods or Secrets left over from CircleCI tasks. Dangling objects may occur if container runner is forcefully deleted, causing the task state-tracking to be lost. GC will only remove objects labelled with app.kubernetes.io/managed-by=circleci-container-agent.
agent.gc.interval	string	"3m"	Frequency of GC runs. Adjust this to balance minimal lingering K8s resources vs. system load. Infrequent runs may reduce the load but could result in excess K8s resources, while frequent runs help minimize resources but could increase system load.
agent.gc.threshold	string	"5h5m"	The age of a Kubernetes object managed by container agent before GC deletes it. This value should be slightly longer than the agent.maxRunTime to prevent premature removal. GC may remove some objects sooner than this threshold, such as task Pod containers that fail their liveness probe.
agent.image	object	{"digest":"","pullPolicy":"Always","registry":"","repository":"circleci/runner-agent","tag":"kubernetes-3"}	Agent image settings. NOTE: Setting an image digest will take precedence over the image tag
agent.livenessProbe	object	{"failureThreshold":5,"httpGet":{"path":"/live","port":7623,"scheme":"HTTP"},"initialDelaySeconds":10,"periodSeconds":10,"successThreshold":1,"timeoutSeconds":1}	Liveness and readiness probe values Ref: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes
agent.log.format	string	"json"	Set the logging format for the container-agent app. Possible values are text, color, json, and none.
agent.log.level	string	"info"	Set the logging level for the container-agent app. Possible values are debug, info, warn, and error. Note: this setting isn't to be confused with the logging sidecar container which is configured under the top-level logging key.
agent.matchLabels.app	string	"container-agent"
agent.maxConcurrentTasks	int	20	Maximum number of tasks that can be run concurrently. IMPORTANT: This concurrency is independent of, and may be limited by, the Runner concurrency of your plan. Configure this value at your own risk based on the resources allocated to your cluster.
agent.maxRunTime	string	"5h"
agent.name	string	""	A (preferably) unique name assigned to this particular container-agent instance. This name will appear in your runners inventory page in the CircleCI UI. If left unspecified, the name will default to the name of the deployment.
agent.nodeSelector	object	{}	Node labels for agent pod assignment Ref: https://kubernetes.io/docs/user-guide/node-selection/
agent.pdb	object	{"create":false,"maxUnavailable":1,"minAvailable":1}	Pod disruption budget settings
agent.podAnnotations	object	{}	Annotations to be added to agent pods
agent.podSecurityContext	object	{}	Security Context policies for agent pods
agent.pullSecrets	list	[]
agent.readinessProbe.failureThreshold	int	3
agent.readinessProbe.httpGet.path	string	"/ready"
agent.readinessProbe.httpGet.port	int	7623
agent.readinessProbe.httpGet.scheme	string	"HTTP"
agent.readinessProbe.initialDelaySeconds	int	10
agent.readinessProbe.periodSeconds	int	10
agent.readinessProbe.successThreshold	int	1
agent.readinessProbe.timeoutSeconds	int	1
agent.replicaCount	int	1
agent.resourceClasses	object	{}	Resource class settings. The tokens specified here will be used to claim tasks & the tasks will be launched with the configured configs Ref: https://circleci.com/docs/container-runner/#resource-class-configuration-custom-pod
agent.resources	object	{}	Agent pod resource configuration Ref: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
agent.runnerAPI	string	"https://runner.circleci.com"	CircleCI Runner API URL
agent.serviceContainers	object	{}	Configuration for service containers. This allows different a different container spec to be passed to your job's service containers. TODO: Full docs link
agent.ssh.controllerName	string	"gateway.envoyproxy.io/gatewayclass-controller"	The name of the Gateway controller. The rerun jobs with SSH feature relies on Gateway API and its TCPRoute resource for SSH access, which requires additional setup of a compatible Gateway controller that supports TCP routing. CircleCI currently recommends Envoy Gateway as a Gateway controller for this. To set it up, read the docs.
agent.ssh.enabled	bool	false	Enable rerunning jobs with SSH. For instructions on how to set up this feature, read the docs.
agent.ssh.existingGatewayClassName	string	""	Option to use an existing GatewayClass instead of creating a new one. The GatewayClass is a cluster-scoped resource defined by the infrastructure provider, which you may wish to manage externally. Note that the configuration specific to SSH routing is defined in the namespace-scoped Gateway resource. For further information, see the Gateway API reference, and the documentation for the Gateway controller specified by agent.ssh.controllerName.
agent.ssh.numPorts	int	20	Specify the total number of ports for SSH. This, along with agent.ssh.startPort, sets the port range. Note that the number of concurrent jobs rerun using SSH will be limited by the size of this range.
agent.ssh.parametersRef	object	{}	Specify controller-specific configuration for the GatewayClass. For details, refer to the Gateway API reference, and the documentation for the Gateway controller specified by agent.ssh.controllerName.
agent.ssh.startPort	int	54782	Define the start port for SSH. This, combined with agent.ssh.numPorts, is used to define a range of ports. Be aware that you may need to configure your firewall or security groups to allow this port range.
agent.terminationGracePeriodSeconds	int	18300	Tasks are drained during the termination grace period, so this should be sufficiently long relative to the maximum run time to ensure graceful shutdown
agent.tolerations	list	[]	Node tolerations for agent scheduling to nodes with taints Ref: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/
logging	object	{"image":{"registry":"","repository":"circleci/logging-collector","tag":3},"rbac":{"create":true,"role":{"name":"logging-collector","rules":[]}},"serviceAccount":{"annotations":{},"create":true,"name":"logging-collector","secret":{"name":"logging-collector-token"}}}	Configuration values for the logging containers. These containers run alongside service containers and stream their logs to the CircleCI UI
logging.serviceAccount	object	{"annotations":{},"create":true,"name":"logging-collector","secret":{"name":"logging-collector-token"}}	A service account with minimal permissions to collect the service container logs
logging.serviceAccount.secret	object	{"name":"logging-collector-token"}	The secret containing the service account token
proxy	object	{"enabled":false,"http":{"auth":{"enabled":false,"password":null,"username":null},"host":"proxy.example.com","port":3128},"https":{"auth":{"enabled":false,"password":null,"username":null},"host":"proxy.example.com","port":3128},"no_proxy":[]}	Proxy Support for Container Agent
proxy.enabled	bool	false	If false, all proxy settings are ignored
proxy.http	object	{"auth":{"enabled":false,"password":null,"username":null},"host":"proxy.example.com","port":3128}	Proxy for HTTP requests
proxy.https	object	{"auth":{"enabled":false,"password":null,"username":null},"host":"proxy.example.com","port":3128}	Proxy for HTTPS requests
proxy.no_proxy	list	[]	List of hostnames, IP CIDR blocks exempt from proxying. Loopback and intra-service traffic is never proxied.
rbac	object	{"clusterRole":{"name":"","rules":[]},"create":true,"role":{"name":"","rules":[]}}	Kubernetes Roles Based Access Control settings
serviceAccount	object	{"annotations":{},"automountServiceAccountToken":true,"create":true,"name":""}	Kubernetes service account settings

Contribution

We are always happy to review pull requests from the community. A few guideline should be followed when preparing a pull request for review.

• Ensure the README file is current by running ./do generate-readme
• Run helm lint to lint the chart
• Add unit tests to cover new changes and functionality
• Run ./do unit-tests to run the chart unit tests locally and ensure they pass
• Include a description of the changes, any testing you've done (we love screenshots), and the reasoning for the changes in your pull request
• Include a description of the change linked to the PR in the CHANGELOG.md file under the # Edge header, using the pull request number as the link anchor