Configuration

The policy-server component has some key configuration files that have a well defined format.

docker-config-json (--docker-config-json-path)

This file mimics the common docker-config-json (5) configuration file. It is used to instruct the policy-server authentication details for OCI registries. Its format is as follows:

{
  "auths": {
    "internal-registry.dev.my-company.com": {
      "auth": "<some base64>"
    },
    "other-internal-registry.dev.my-company.com:5001": {
      "auth": "<some base64>"
    },
    "ghcr.io": {
      "auth": "<some base64>"
    },
  }
}

Notes:

• Each key will be requested strictly by the host in the URL. This host may contain a port if the policy module URI has a host:port form.
• This file only honors the auths key as opposes to the original docker-config-json file that contains, for instance, HttpHeaders. Keys other than "auths" in the toplevel object will be ignored.
• The <some base64> is the string username:password (where password is usually a token), base-64 encoded, as docker login produces.

sources-path (--sources-path)

The sources file is a YAML file that contains information about valid ways to verify the identity of the remote server (the source). Its format is as follows:

insecure_sources:
  - local-registry.dev.my-company.com
  - "other-local-registry.dev.my-company.com:5001"
source_authorities:
  "internal-registry.dev.my-company.com":
  - type: Path
    path: /local/path/to/internal-registry-dev-mycompany-com.pki
  "other-internal-registry.dev.my-company.com:5001":
  - type: Path
    path: /local/path/to/other-internal-registry-dev-mycompany-com.pki
  - type: Data
    data: |
      PEM-cert2
      line1
      line2

Notes:

• Insecure sources imply a number of retries if the policy cannot be downloaded:
  • Try to download with TLS and system certificate authorities -- verifying identity of the remote server. If fails,
  • Try to download with TLS -- not verifying identity of the remote server. If fails,
  • Try to download without TLS
• Either insecure_sources or source_authorities has to be provided. Both can be provided if needed.
• source_authorities allow you to provide a specific certificate authority the host can be validated against.
• Each key will be requested strictly by the host in the URL. This host may contain a port if the policy module URI has a host:port form.
• The certificate and certificate chain can be DER or PEM encoded.
• The certificate can be read from the local filesystem using the path key, or could be embedded into the YAML file using the data key.

policies (--policies)

The policy mapping is a YAML file containing a map of policies to be loaded by the policy server. The file looks as follows:

psp-apparmor:
  url: registry://ghcr.io/kubewarden/policies/psp-apparmor:v0.1.3
psp-capabilities:
  url: registry://ghcr.io/kubewarden/policies/psp-capabilities:v0.1.2
  settings:
    allowed_capabilities: ["*"]
    required_drop_capabilities: ["KILL"]

Notes:

• Top level keys refer to the name of the instantiation of a policy. A policy can be repeated multiple times in several instantiations.
• settings is a free form map forwarded to the policy. What settings the policy supports is up to the policy author and to what the policy documents.

verification (--verification-path)

The verification file is a YAML file that contains information for verification of policies via Sigstore. Its format is as described in Kubewarden's RFC 3.