rkt/Documentation/configuration.md

rkt configuration

rkt reads configuration from two directories - a system directory and a local directory. The system directory defaults to /usr/lib/rkt and the local directory /etc/rkt, but both can be overridden via command-line flags.

rkt looks for configuration files inside subdirectories of these two directories. It ignores everything but regular files with .json extension. This means rkt does not search for the files by recursively going down the directory tree. This also means that users are free to put some additional files there (e.g. documentation).

Every configuration file has two common fields: rktKind and rktVersion. Both are strings, and the rest of the fields are specified by that pair. The currently supported kinds and versions are described below. These fields must be specified and cannot be empty.

rktKind describes the type of the configuration. This is to avoid putting unrelated values into single monolithic file.

rktVersion allows configuration versioning for each kind of configuration. A new version should be introduced when doing some backward-incompatible changes: for example, when removing a field or incompatibly changing its semantics. When a new field is added, a default value should be specified for it, documented, and used when the field is absent in file. This way, an older version of rkt can work with newer-but-compatible versions of configuration files, and newer versions of rkt can still work with older versions of configuration files.

The configuration in the system directory can be overridden by configuration in the local directory. The semantics of configuration override are specific to the kind and version of the configuration file and are described below. Filenames do not play any role in overriding.

Configuration kinds

rktKind: auth

This kind of configuration is used to set up necessary credentials when downloading images and signatures. The configuration files should be placed inside the auth.d subdirectory (e.g., in the case of the default system/local directories, in /usr/lib/rkt/auth.d and/or /etc/rkt/auth.d).

rktVersion: v1

Description and examples

This version of auth configuration specifies three additional fields: domains, type and credentials.

The domains field is an array of strings describing hosts for which the following credentials should be used. Each entry must consist of a host/port combination in a URL as specified by RFC 3986. This field must be specified and cannot be empty.

The type field describes the type of credentials to be sent. This field must be specified and cannot be empty.

The credentials field is defined by the type field. It should hold all the data that are needed for successful authentication with the given hosts.

This version of auth configuration supports two methods - basic HTTP authentication and OAuth Bearer Token.

Basic HTTP authentication requires two things - a user and a password. To use this type, define type as basic and the credentials field as a map with two keys - user and password. These fields must be specified and cannot be empty. For example:

{
	"rktKind": "auth",
	"rktVersion": "v1",
	"domains": ["coreos.com", "tectonic.com"],
	"type": "basic",
	"credentials": {
		"user": "foo",
		"password": "bar"
	}
}

OAuth Bearer Token authentication requires only a token. To use this type, define type as oauth and the credentials field as a map with only one key - token. This field must be specified and cannot be empty. For example:

{
	"rktKind": "auth",
	"rktVersion": "v1",
	"domains": ["coreos.com", "tectonic.com"],
	"type": "oauth",
	"credentials": {
		"token": "sometoken"
	}
}

Override semantics

Overriding is done for each domain. That means that the user can override authentication type and/or credentials used for each domain. As an example, consider this system configuration:

/usr/lib/rkt/auth.d/coreos.json:

{
	"rktKind": "auth",
	"rktVersion": "v1",
	"domains": ["coreos.com", "tectonic.com", "kubernetes.io"],
	"type": "oauth",
	"credentials": {
		"token": "common-token"
	}
}

If only this configuration file is provided then when downloading data from either coreos.com, tectonic.com or kubernetes.io, rkt would send an HTTP header of: Authorization: Bearer common-token.

But with additional configuration provided in the local configuration directory, this can be overridden. For example, given the above system configuration and the following local configurations:

/etc/rkt/auth.d/specific-coreos.json:

{
	"rktKind": "auth",
	"rktVersion": "v1",
	"domains": ["coreos.com"],
	"type": "basic",
	"credentials": {
		"user": "foo",
		"password": "bar"
	}
}

/etc/rkt/auth.d/specific-tectonic.json:

{
	"rktKind": "auth",
	"rktVersion": "v1",
	"domains": ["tectonic.com"],
	"type": "oauth",
	"credentials": {
		"token": "tectonic-token"
	}
}

The result is that when downloading data from kubernetes.io, rkt still sends Authorization: Bearer common-token, but when downloading from coreos.com, it sends Authorization: Basic Zm9vOmJhcg== (i.e. foo:bar encoded in base64). For tectonic.com, it will send Authorization: Bearer tectonic-token.

Note that within a particular configuration directory (either system or local), it is a syntax error for the same domain to be defined in multiple files.

rktKind: dockerAuth

This kind of configuration is used to set up necessary credentials when downloading data from Docker registries. The configuration files should be placed inside auth.d subdirectory (e.g. in /usr/lib/rkt/auth.d or /etc/rkt/auth.d).

rktVersion: v1

Description and examples

This version of dockerAuth configuration specifies two additional fields: registries and credentials.

The registries field is an array of strings describing Docker registries for which the associated credentials should be used. A short list of popular Docker registries is below. This field must be specified and cannot be empty.

credentials field holds the necessary data to authenticate against the Docker registry. This field must be specified and cannot be empty.

Currently, Docker registries only support basic HTTP authentication, so credentials field has two subfields - user and password. These fields have to be specified and cannot be empty.

Some popular Docker registries:

• index.docker.io (this is used when no Docker registry is specified in a reference on the rkt command line, as in docker://redis)
• quay.io
• gcr.io

Example dockerAuth configuration:

{
	"rktKind": "dockerAuth",
	"rktVersion": "v1",
	"registries": ["index.docker.io", "quay.io"],
	"credentials": {
		"user": "foo",
		"password": "bar"
	}
}

Override semantics

Overriding is done for each registry. That means that the user can override credentials used for each registry. For example, given this system configuration:

In /usr/lib/rkt/auth.d/docker.json:

{
	"rktKind": "dockerAuth",
	"rktVersion": "v1",
	"registries": ["index.docker.io", "gcr.io", "quay.io"],
	"credentials": {
		"user": "foo",
		"password": "bar"
	}
}

If only this configuration file is provided, then when downloading images from either index.docker.io, gcr.io, or quay.io, rkt would use user foo and password bar.

But with additional configuration provided in the local configuration directory, this can be overridden. For example, given the above system configuration and the following local configuration:

/etc/rkt/auth.d/specific-quay.json:

{
	"rktKind": "dockerAuth",
	"rktVersion": "v1",
	"registries": ["quay.io"],
	"credentials": {
		"user": "baz",
		"password": "quux"
	}
}

/etc/rkt/auth.d/specific-gcr.json:

{
	"rktKind": "dockerAuth",
	"rktVersion": "v1",
	"domains": ["gcr.io"],
	"credentials": {
		"user": "goo",
		"password": "gle"
	}
}

The result is that when downloading images from index.docker.io, rkt still sends user foo and password bar, but when downloading from quay.io, it uses user baz and password quux; and for gcr.io it will use user goo and password gle.

Note that within a particular configuration directory (either system or local), it is a syntax error for the same Docker registry to be defined in multiple files.