Configuration¶

The native configuration format for Conch is a TOML file, passed as a command-line argument --config.

If you are installing Conch via Helm with a values.yaml then these settings can be set under the config key, e.g.:

config:
  issuer: "https://example.com"

All the examples below show the syntax for both.

issuer¶

Type:: String (URL)

This must be set as a string containing the URL of the OIDC issuer. It should be the path that contains the .well-known/openid-configuration location. For example, this could be set to "https://keycloak.example.com/realms/example" (such that https://keycloak.example.com/realms/example/.well-known/openid-configuration exists). The issuer must support OpenID Provider Issuer discovery.

client_id¶

Type:: String

The OIDC client ID that is configured at issuer. For example, it could be set to "clifton".

signing_key_path¶

Type:: String (path)

This must be set to the path on disk where the private SSH key is stored.

platforms¶

Type:: Table

The name of the table should be a string of the name of the platform. It must contain the following keys:

alias¶: a short string which can be used as an SSH config Host name. You should avoid making the alias a resolvable domain name as it works best if it forms its own namespace.

hostname¶: a string containing the real hostname of the platform to SSH into.

proxy_jump¶: a string containing the hostname to be used by ProxyJump.

For example, it might look like:

[platforms."batch.cluster1.example"]
alias = "cluster1.example"
hostname = "1.access.example.com"
proxy_jump = "bastion.example.com"

[platforms."batch.cluster2.example"]
alias = "cluster2.example"
hostname = "2.access.example.com"
proxy_jump = "bastion.example.com"

platforms:
  batch.cluster1.example:
    alias: "cluster1.example"
    hostname: "1.access.example.com"
    proxy_jump: "bastion.example.com"
  batch.cluster2.example:
    alias: "cluster2.example"
    hostname: "2.access.example.com"
    proxy_jump: "bastion.example.com"

mappers¶

Type:: Array of Tables

This must be set to a list containing the identity mappers to apply. Each of these configure which claims (or combinations thereof) should be put into the certificate principals. The available options are:

single¶

Type:: String

A claim containing a single string should be placed verbatim into the principal list.

[[mappers]]
single = "email"

mappers:
  - single: "email"

list¶

Type:: String

A claim containing a JSON list of strings, each of which will be mapped directly into the principal list.

[[mappers]]
list = "names"

mappers:
  - list: "names"

project_infra¶

Type:: String

This will generate a principal for each of the projects passed in.

"v1": Create principals of the form <short_name>.<project-name>. The prefix <short_name> comes from a string claim short_name and the <project-name> comes from each of the project names defined in the projects claim.

[[mappers]]
project_infra = "v1"

mappers:
  - project_infra: "v1"

You can set as many mappers as you like, just repeat the table:

[[mappers]]
single = "email"

[[mappers]]
single = "short_name"

[[mappers]]
list = "names"

mappers:
  - single: "email"
  - single: "short_name"
  - list: "names"

extensions¶

Type:: Array of Strings
Default:: []

A list of the SSH certificate extensions that should be enabled on any generated certificates. For example:

extensions = ["permit-pty", "permit-agent-forwarding"]