By default, the Coder server runsbuilt-in provisioner daemons,which executeterraform during workspace and template builds. However, thereare often benefits to running external provisioner daemons:

• Secure build environments: Run build jobs in isolated containers,preventing malicious templates from gaining sh access to the Coder host.

• Isolate APIs: Deploy provisioners in isolated environments (on-prem, AWS,Azure) instead of exposing APIs (Docker, Kubernetes, VMware) to the Coderserver. SeeProvider Authenticationfor more details.

• Isolate secrets: Keep Coder unaware of cloud secrets, manage/rotatesecrets on provisioner servers.

• Reduce server load: External provisioners reduce load and build queuetimes from the Coder server. SeeScaling Coder for moredetails.

Each provisioner runs a singleconcurrent workspace build.For example, running 30 provisioner containers will allow 30 users to startworkspaces at the same time.

Provisioners are started with thecoder provisioner start command inthefull Coder binary. Keep readingto learn how to start provisioners via Docker, Kubernetes, Systemd, etc.

You can use the dashboard, CLI, or API tomanage provisioners.

Authentication

The provisioner daemon must authenticate with your Coder deployment.

Provisioner Tags

You can useprovisioner tags to control which provisioners can pick up buildjobs from templates (and corresponding workspaces) with matching explicit tags.

Provisioners have two implicit tags:scope andowner. Coder sets these tagsautomatically.

• Organization-scoped provisioners always have the implicit tagsscope=organization owner=""
• User-scoped provisioners always have the implicit tagsscope=user owner=<uuid>

For example:

This can also be done in the UI when building a template:

Alternatively, a template can target a provisioner viaworkspace tagsinside the Terraform. See theworkspace tags documentationfor more information.

A provisioner can run a given build job if one of the below is true:

1. A job with no explicit tags can only be run on a provisioner with no explicittags. This way you can introduce tagging into your deployment withoutdisrupting existing provisioners and jobs.
2. If a job has any explicit tags, it can only run on a provisioner with thoseexplicit tags (the provisioner could have additional tags).

The external provisioner in the above example can run build jobs in the sameorganization with tags:

• environment=on_prem
• datacenter=chicago
• environment=on_prem datacenter=chicago

However, it will not pick up any build jobs that do not have either of theenvironment ordatacenter tags set. It will also not pick up any build jobsfrom templates with the tagscope=user set, or build jobs from templates indifferent organizations.

This is illustrated in the below table:

Types of provisioners

Provisioners can broadly be categorized by scope:organization oruser. Thescope of a provisioner can be specified with-tag=scope=<scope> whenstarting the provisioner daemon. Only users with at least theTemplate Admin role or higher may createorganization-scoped provisioner daemons.

There are two exceptions:

• Built-in provisioners arealways organization-scoped.
• External provisioners started using apre-shared key (PSK) are alwaysorganization-scoped.

Organization-Scoped Provisioners

Organization-scoped Provisioners can pick up build jobs created by any user.These provisioners always have the implicit tagsscope=organization owner="".

If you omit the--org argument, the provisioner will be assigned to thedefault organization.

User-scoped Provisioners

User-scoped Provisioners can only pick up build jobs created fromuser-tagged templates. Unlike the other provisioner types, any Coder user canrun user provisioners, but they have no impact unless there exists at least onetemplate with thescope=user provisioner tag.

Example: Running an external provisioner with Helm

Coder provides a Helm chart for running external provisioner daemons, which youwill use in concert with the Helm chart for deploying the Coder server.

1. Create a provisioner key:

   coder provisioner keys create my-cool-key --org default# Optionally, you can specify tags for the provisioner key:# coder provisioner keys create my-cool-key --org default --tag location=auh --tag kind=k8sSuccessfully created provisioner key kubernetes-key! Save this authenticationtoken, it will not be shown again.<key omitted>

2. Store the key in a kubernetes secret:

   kubectl create secret generic coder-provisioner-keys --from-literal=my-cool-key=`<key omitted>`

3. Create aprovisioner-values.yaml file for the provisioner daemons Helmchart. For example:

   coder: env: - name: CODER_URL value: "https://coder.example.com" replicaCount: 10provisionerDaemon: # NOTE: in older versions of the Helm chart (2.17.0 and below), it is required to set this to an empty string. pskSecretName: "" keySecretName: "coder-provisioner-keys" keySecretKey: "my-cool-key"

   This example creates a deployment of 10 provisioner daemons (for 10concurrent builds) authenticating using the above key. The daemons willauthenticate using the provisioner key created in the previous step andacquire jobs matching the tags specified when the provisioner key wascreated. The set of tags is inferred automatically from the provisioner key.

   Refer to thevalues.yamlfile for the coder-provisioner chart for information on what values can bespecified.

4. Install the provisioner daemon chart

   helm install coder-provisioner coder-v2/coder-provisioner \ --namespace coder \ --version <your version> \ --values provisioner-values.yaml

   You can verify that your provisioner daemons have successfully connected toCoderd by looking for a debug log message that saysprovisioner: successfully connected to coderd from each Pod.

Example: Running an external provisioner on a VM

Example: Running an external provisioner via Docker

Disable built-in provisioners

As mentioned above, the Coder server will run built-in provisioners by default.This can be disabled with a server-wideflag or environment variable.

Prometheus metrics

Coder provisioner daemon exports metrics via the HTTP endpoint, which can beenabled using either the environment variableCODER_PROMETHEUS_ENABLE or theflag--prometheus-enable.

The Prometheus endpoint address ishttp://localhost:2112/ by default. You canuse either the environment variableCODER_PROMETHEUS_ADDRESS or the flag--prometheus-address <network-interface>:<port> to select a different listenaddress.

If you have provisioners daemons deployed as pods, it is advised to monitor themseparately.

Next

• Manage Provisioners