spec

---
name: atc

description: |
  The ATC (Air Traffic Controller) provides UI and API access. It is
  responsible for scheduling builds and detecting versions of your resources.

templates:
  atc_ctl.erb: bin/atc_ctl
  tls_cert.erb: config/tls_cert
  tls_key.erb: config/tls_key
  cf_ca_cert.erb: config/cf_ca_cert
  github_ca_cert.erb: config/github_ca_cert
  ldap_ca_cert.erb: config/ldap_ca_cert
  oauth_ca_cert.erb: config/oauth_ca_cert
  oidc_ca_cert.erb: config/oidc_ca_cert
  postgres_ca_cert.erb: config/postgres_ca_cert
  postgres_client_cert.erb: config/postgres_client_cert
  postgres_client_key.erb: config/postgres_client_key
  vault_ca_cert.erb: config/vault_ca_cert
  vault_client_cert.erb: config/vault_client_cert
  vault_client_key.erb: config/vault_client_key
  credhub_ca_cert.erb: config/credhub_ca_cert
  credhub_client_cert.erb: config/credhub_client_cert
  credhub_client_key.erb: config/credhub_client_key
  token_signing_key.erb: config/token_signing_key
  downgrade_db.erb: bin/experimental_downgrade_db
  syslog_ca_cert.erb: config/syslog_ca_cert

packages:
  - pid_utils
  - atc
  - fly

consumes:
- name: db
  type: postgresql
  optional: true
- name: postgres
  type: database
  optional: true

provides:
- name: atc
  type: atc
  properties:
  - bind_port
  - tls_bind_port

properties:
  bind_ip:
    description: |
      IP address on which the ATC should listen for HTTP traffic.
    default: 0.0.0.0

  bind_port:
    description: |
      Port on which the ATC should listen for HTTP traffic.
    default: 8080

  tls_bind_port:
    description: |
      Port on which the ATC should listen for HTTPS traffic.
    default: 4443

  tls_cert:
    description: |
      SSL cert to use for HTTPS.

      If not specified, only HTTP will be enabled.

  tls_key:
    description: |
      SSL private key to use for encrypting HTTPS traffic.

      If not specified, only HTTP will be enabled.

  external_url:
    description: |
      Externally reachable URL of the ATCs. Required for OAuth. This will be
      auto-generated using the IP of each ATC VM if not specified, however
      this is only a reasonable default if you have a single instance.

      Typically this is the URL that you as a user would use to reach your CI.
      For multiple ATCs it would go to some sort of load balancer.
    example: https://ci.concourse-ci.org

  peer_url:
    description: |
      Address used internally to reach the ATC. This will be auto-generated
      using the IP of each ATC VM if not specified.

      Note that this refers to an *individual ATC*, not the whole cluster. This
      property is only useful if you're deploying in a way that cannot
      autodetect its own IP, e.g. a `bosh-init` deployment.

      You should otherwise leave this value blank.

  x_frame_options:
    description: |
        The value to set for X-Frame-Options.

        If omitted, the header is not set.
    default: ""

  log_level:
    description: |
      The log level for the ATC. When set to debug, you'll see a lot more
      information about scheduling, resource scanning, etc., but it'll be quite
      chatty.
    default: info

  log_db_queries:
    description: |
      Log database queries. Log level is debug, so you'll need to set the
      log_level property as well. This is mainly useful for Concourse
      developers to analyze query counts.
    default: false

  encryption_key:
    description: |
      A 16 or 32 byte passphrase. This is used to generate an AES key to encrypt
      sensitive iinformation in the database.

      If specified, all existing data will be encrypted on start and any new
      data will be encrypted.

  old_encryption_key:
    description: |
      The key used previously to encrypt sensitive information in the database.

      To rotate your encryption key, set both old_encryption_key and
      encryption_key. This will result in the ATC re-encrypting all data on
      start.

      To disable encryption, specify old_encryption_key and do *not* set
      encryption_key. This will result in the ATC decrypting all data on start,
      restoring it to plaintext.

  cookie_secure:
    description: Set secure flag on auth cookies
    default: false

  auth_duration:
    description: |
      Length of time for which tokens are valid. Afterwards, users will have to log back in.
      Use Go duration format (48h = 48 hours).
    default: 24h

  token_signing_key:
    type: rsa
    description: |
      PEM RSA private key used for minting ATC tokens.
    example:
      private_key: |
         -----BEGIN RSA PRIVATE KEY-----
         ...
         -----END RSA PRIVATE KEY-----
      public_key: |
         -----BEGIN PUBLIC KEY-----
         ...
         -----END PUBLIC KEY-----

  add_local_users:
    description: |
      List of local concourse users to add with their bcrypted passwords.
      bcrypted password must have a strength of 10 or higher or the user will not be able to login
    default: []
    example:
    - some-user:$2a$10$sKZelZprWWcBAWbp28rB1uFef0Ybxsiqh05uo.H8EIm0sWc6IZGJu
    - some-other-user:$2a$10$.YIYH.5EWQcCvfE49xH/.OhIhGFiNtn.tQq.4pznpcrqZvoLxuKeC

  github_auth.client_id:
    description: |
      GitHub client ID to use for OAuth.

      The application must be configured with its callback URL as
      `{external_url}/sky/issuer/callback` (replacing `{external_url}`
      with the actual value).
    default: ""

  github_auth.client_secret:
    description: |
      GitHub client secret to use for OAuth.

      The application must be configured with its callback URL as
      `{external_url}/sky/issuer/callback` (replacing `{external_url}`
      with the actual value).
    default: ""

  github_auth.host:
    description: |
      Override default hostname for Github Enterprise. (No scheme, No trailing slash)
    example: "github.example.com"
    default: ""

  github_auth.ca_cert:
    type: certificate
    description: |
      GitHub Enterprise CA Certificate.

  cf_auth.client_id:
    description: UAA client ID to use for OAuth.
    default: ""

  cf_auth.client_secret:
    description: UAA client secret to use for OAuth.
    default: ""

  cf_auth.api_url:
    description: Cloud Foundry api endpoint url.
    default: ""

  cf_auth.ca_cert:
    type: certificate
    description: |
      Cloud Foundry CA Certificate.

  ldap_auth.host:
    description: The host and optional port of the LDAP server. If port isn't supplied, it will be guessed based on the TLS configuration. 389 or 636.
    default: ""

  ldap_auth.bind_dn:
    description: Bind DN for searching LDAP users and groups. Typically this is a read-only user.
    default: ""

  ldap_auth.bind_pw:
    description: Bind Password for the user specified by 'bind-dn'.
    default: ""

  ldap_auth.insecure_no_ssl:
    description: Required if LDAP host does not use TLS.
    default: false

  ldap_auth.insecure_skip_verify:
    description: Skip certificate verification.
    default: false

  ldap_auth.start_tls:
    description: Start on insecure port, then negotiate TLS.
    default: false

  ldap_auth.ca_cert:
    type: certificate
    description: |
      The CA certificate for the LDAP auth provider's endpoints.

  ldap_auth.user_search_base_dn:
    description: BaseDN to start the search from. For example 'cn=users,dc=example,dc=com'.
    default: ""

  ldap_auth.user_search_filter:
    description: Optional filter to apply when searching the directory. For example '(objectClass=person)'.
    default: ""

  ldap_auth.user_search_username:
    description: Attribute to match against the inputted username. This will be translated and combined with the other filter as '(<attr>=<username>)'.
    default: ""

  ldap_auth.user_search_scope:
    description: Can either be 'sub' - search the whole sub tree or 'one' - only search one level. Defaults to 'sub' if empty.
    default: ""

  ldap_auth.user_search_id_attr:
    description: A mapping of attributes on the user entry to claims. Defaults to 'uid' if empty.
    default: ""

  ldap_auth.user_search_email_attr:
    description: A mapping of attributes on the user entry to claims. Defaults to 'mail' if empty.
    default: ""

  ldap_auth.user_search_name_attr:
    description: A mapping of attributes on the user entry to claims.
    default: ""

  ldap_auth.group_search_base_dn:
    description: BaseDN to start the search from. For example 'cn=groups,dc=example,dc=com'.
    default: ""

  ldap_auth.group_search_filter:
    description: Optional filter to apply when searching the directory. For example '(objectClass=posixGroup)'.
    default: ""

  ldap_auth.group_search_scope:
    description: Can either be 'sub' - search the whole sub tree or 'one' - only search one level. Defaults to 'sub' if empty.
    default: ""

  ldap_auth.group_search_user_attr:
    description: Adds an additional requirement to the filter that an attribute in the group match the user's attribute value. The exact filter being added is (<groupAttr>=<userAttrvalue>).
    default: ""

  ldap_auth.group_search_group_attr:
    description: Adds an additional requirement to the filter that an attribute in the group match the user's attribute value. The exact filter being added is (<groupAttr>=<userAttrvalue>)
    default: ""

  ldap_auth.group_search_name_attr:
    description: The attribute of the group that represents its name.
    default: ""

  generic_oauth.client_id:
    description: Application client ID for enabling generic OAuth.
    default: ""

  generic_oauth.client_secret:
    description: Application client secret for enabling generic OAuth.
    default: ""

  generic_oauth.auth_url:
    description: Generic OAuth provider authorization endpoint url.
    default: ""

  generic_oauth.token_url:
    description: Generic OAuth provider token endpoint URL.
    default: ""

  generic_oauth.userinfo_url:
    description: Generic OAuth provider user info endpoint URL.
    default: ""

  generic_oauth.scopes:
    description: OAuth scopes to request during authorization.
    default: []

  generic_oauth.groups_key:
    description: Groups claim key used to map groups from the OAuth userinfo/token
    default: ""

  generic_oauth.display_name:
    description: Name of the authentication method to be displayed on the Web UI
    default: ""

  generic_oauth.ca_cert:
    type: certificate
    description: |
      The CA certificate for the Generic OAuth provider's endpoints.

  generic_oidc.client_id:
    description: Application client ID for enabling generic OIDC.
    default: ""

  generic_oidc.client_secret:
    description: Application client secret for enabling generic OIDC.
    default: ""

  generic_oidc.issuer:
    description: Generic OIDC provider issuer url.
    default: ""

  generic_oidc.scopes:
    description: OIDC scopes to request during authorization.
    default: []

  generic_oidc.groups_key:
    description: Groups claim key used to map groups from the OIDC userinfo/token
    default: ""

  generic_oidc.display_name:
    description: Name of the authentication method to be displayed on the Web UI
    default: ""

  generic_oidc.ca_cert:
    type: certificate
    description: |
      The CA certificate for the Generic OIDC provider's endpoints.

  main_team.auth.allow_all_users:
    description: |
      Whitelist all authenticated users for the main team.
    default: false

  main_team.auth.local.users:
    description: |
      An array of local users that are authorized for the main team.
    default: []

  main_team.auth.github.users:
    default: []
    description: |
      An array of GitHub userids/logins that are authorized for the main team
    example:
    - my-github-login

  main_team.auth.github.orgs:
    default: []
    description: |
      An array of GitHub orgs that are authorized for the main team
    example:
    - my-github-org

  main_team.auth.github.teams:
    default: []
    description: |
      An array of GitHub teams that are authorized for the main team
    example:
    - my-github-org:my-github-team

  main_team.auth.cf.users:
    description: |
      List of CloudFoundry userids/usernames that are authorized for the main team
    default: []
    example:
    - my-username

  main_team.auth.cf.orgs:
    description: |
      List of CloudFoundry Orgs that are authorized for the main team
    default: []
    example:
    - myorg

  main_team.auth.cf.spaces:
    description: |
      List of CloudFoundry Spaces that are authorized for the main team
    default: []
    example:
    - myorg:myspace

  main_team.auth.ldap.users:
    description: |
      List of LDAP users that are authorized for the main team
    default: []
    example:
    - my-username

  main_team.auth.ldap.groups:
    description: |
      List of LDAP groups that are authorized for the main team
    default: []
    example:
    - my-group

  main_team.auth.oauth.users:
    description: |
      List of Generic OAuth users that are authorized for the main team
    default: []
    example:
    - my-username

  main_team.auth.oauth.groups:
    description: |
      List of Generic OAuth groups that are authorized for the main team
    default: []
    example:
    - my-group

  main_team.auth.oidc.users:
    description: |
      List of Generic OIDC users that are authorized for the main team
    default: []
    example:
    - my-username

  main_team.auth.oidc.groups:
    description: |
      List of Generic OIDC groups that are authorized for the main team
    default: []
    example:
    - my-group

  intercept_idle_timeout:
    description: Length of time for a intercepted session to be idle before terminating, in Go duration format.
    example: 5m

  default_check_interval:
    description: |
      The interval, in Go duration format (1m = 1 minute), on which to check
      for new versions of resources.

      This can also be specified on a per-resource basis by specifying
      `check_every` on the resource config.
    default: 1m

  default_resource_type_check_interval:
    description: |
      The interval, in Go duration format (1m = 1 minute), on which to check
      for new versions of resource types.

      This can also be specified on a per-resource_type basis by specifying
      `check_every` on the resource type config.
    default: 1m

  gc_interval:
    description: |
      The interval, in Go duration format (1m = 1 minute), on which to garbage
      collect containers, volumes, and other internal data.
    default: 30s

  build_tracker_interval:
    description: |
      The interval, in Go duration format (1m = 1 minute), on which to run
      build tracking to keep track of build status.
    default: 10s

  resource_cache_cleanup_interval:
    description: |
      The interval, in Go duration format (1m = 1 minute), on which to check
      for and release old caches of resource versions.
    default: 30s

  container_placement_strategy:
    description: |
      Method by which a worker is selected during container placement.

      Options are "volume-locality" and "random".
    default: "volume-locality"

  baggageclaim_response_header_timeout:
    description: |
      How long to wait for Baggageclaim to send the response header. Use Go duration
      format (1m = 1 minute).
    default: 1m

  postgresql_database:
    description: |
      Name of the database to use from the `postgresql` link.

  postgresql.host:
    description: |
      IP address or DNS name of a PostgreSQL server to connect to.

      If not specified, one will be autodiscovered via BOSH links.

  postgresql.port:
    description: |
      Port on which to connect to the server specified by `postgresql.host`.

      If `postgresql.host` is not specified, this will be autodiscovered via
      BOSH links, along with the host.
    default: 5432

  postgresql.address:
    description: |
      Deprecated. Shorthand for specifying `postgresql.host` and
      `postgresql.port`.

  postgresql.database:
    description: |
      Name of the database to use.
    default: atc

  postgresql.role.name:
    description: |
      Name of role to connect with.
    default: atc

  postgresql.role.password:
    description: |
      Password to use when connecting.

  postgresql.sslmode:
    description: |
      Whether or not to use SSL. Defaults to `verify-ca` when `postgresql.address`
      or `postgresql.host` is provided. Otherwise, defaults to `disable`.

  postgresql.ca_cert:
    type: certificate
    description: |
      CA certificate to verify the server against.

  postgresql.client_cert:
    type: certificate
    description: |
      Client certificate to use when connecting with the server.

  postgresql.connect_timeout:
    description: |
      Dialing timeout, in Go duration format (1m = 1 minute). 0 means wait indefinitely.
    default: 5m

  datadog.agent_host:
    description: |
      If configured, detailed metrics will be emitted to the specified Datadog Agent's
      dogstatsd server.

  datadog.agent_port:
    description: |
      Port of the Datadog Agent's dogstatsd server to emit events to.
    default: 8125

  datadog.prefix:
    description: |
      An optional prefix for emitted Datadog events.

  riemann.host:
    description: |
      If configured, detailed metrics will be emitted to the specified Riemann
      server.
    default: ""

  riemann.port:
    description: |
      Port of the Riemann server to emit events to.
    default: 5555

  riemann.service_prefix:
    description: |
      An optional prefix for emitted Riemann services
    default: ""

  riemann.tags:
    description: |
      An optional map of tags in key: value format
    default: {}
    example:
      env: dev
      foo: bar

  prometheus.bind_ip:
    description: |
      If configured, expose Prometheus metrics at specified address

  prometheus.bind_port:
    description: |
      If configured, expose Prometheus metrics at specified port

  influxdb.url:
    description: |
      If configured, detailed metrics will be emitted to the specified InfluxDB
      server.
  influxdb.database:
    description: |
      InfluxDB database to which metrics will be emitted.
    default: ""
  influxdb.username:
    description: |
      InfluxDB username for authorizing access.
    default: ""
  influxdb.password:
    description: |
      InfluxDB password for authorizing access.
    default: ""
  influxdb.insecure_skip_verify:
    description: |
      Skip SSL verification when emitting to InfluxDB.
    default: false

  vault.url:
    description: |
      Vault server URL to use for parameterizing credentials.
  vault.cache:
    description: |
      Enable Vault cache for secrets lease duration in memory.
    default: false
  vault.path_prefix:
    description: |
      Path under which to namespace team/pipeline credentials.
    default: /concourse
  vault.tls.ca_cert:
    type: certificate
    description: |
      A PEM-encoded CA cert to use to verify the Vault server SSL cert.
  vault.tls.server_name:
    description: |
      If set, is used to set the SNI host when connecting via TLS.
    default: ""
  vault.tls.insecure_skip_verify:
    description: |
      Enable insecure SSL verification.
    default: false
  vault.tls.client_cert:
    type: certificate
    description: |
      Client certificate for Vault TLS auth.
  vault.auth.client_token:
    description: |
      Client token to use for accessing your Vault server.
    default: ""
  vault.auth.backend:
    description: |
      Auth backend to use for logging in to Vault.
    default: ""
  vault.auth.params:
    description: |
      Key-value parameters to provide when logging in with the backend.
    default: {}
    example: {role_id: abc123, secret_id: def456}

  credhub.url:
    description: |
      CredHub server address used to access secrets.
    example: "https://credhub-server:9000"
  credhub.path_prefix:
    description: |
      Path under which to namespace team/pipeline credentials.
    default: /concourse
  credhub.tls.ca_cert:
    type: certificate
    description: |
      A PEM-encoded CA cert to use to verify the Credhub server SSL cert.
  credhub.tls.client_cert:
    type: certificate
    description: |
      Client certificate for CredHub mutual TLS auth.
  credhub.tls.insecure_skip_verify:
    description: |
      Enable insecure SSL verification.
    default: false
  credhub.client_id:
    description: |
      Client ID for CredHub authorization.
  credhub.client_secret:
    description: |
      Client secret for CredHub authorization.

  aws_ssm.region:
    description: |
      AWS region to use for fetching SSM parameters.
  aws_ssm.access_key:
    description: |
      AWS Access key ID used as credentials for accessing SSM parameters.
  aws_ssm.secret_key:
    description: |
      AWS Secret Access Key used as credentials for accessing SSM parameters.
  aws_ssm.session_token:
    description: |
      AWS Session Token used as credentials for accessing SSM parameters.
  aws_ssm.pipeline_secret_template:
    description: |
      AWS SSM parameter name template used to resolve pipeline specific secrets. If this flag contains slashes, be sure
      to start it with a /. Maximum 5 slashes are permitted by AWS in parameter names.
    default: /concourse/{{.Team}}/{{.Pipeline}}/{{.Secret}}
  aws_ssm.team_secret_template:
    description: |
      AWS SSM parameter name template used to resolve team specific secrets. If this flag contains slashes, be sure
      to start it with a /. Maximum 5 slashes are permitted by AWS in parameter names.
      names.
    default: /concourse/{{.Team}}/{{.Secret}}

  aws_secretsmanager.region:
    description: |
      AWS region to use for fetching entries from SecretsManager.
  aws_secretsmanager.access_key:
    description: |
      AWS Access key ID used as credentials for accessing SecretsManager.
  aws_secretsmanager.secret_key:
    description: |
      AWS Secret Access Key used as credentials for accessing SecretsManager.
  aws_secretsmanager.session_token:
    description: |
      AWS Session Token used as credentials for accessing SecretsManager.
  aws_secretsmanager.pipeline_secret_template:
    description: |
      AWS SecretsManager secret name template used to resolve pipeline specific secrets.
    default: /concourse/{{.Team}}/{{.Pipeline}}/{{.Secret}}
  aws_secretsmanager.team_secret_template:
    description: |
      AWS SecretsManager secret name template used to resolve team specific secrets.
    default: /concourse/{{.Team}}/{{.Secret}}

  build_log_retention.default:
    description: |
      Default (can be overriden by job) number of build logs to retain,
      0 (or not set) means retain all (database will grow indefinitely).
    example: 100
  build_log_retention.maximum:
    description: |
      If set, this will cap the maximum number of build logs to retain for any job,
      capping any value set in a job itself or the build_log_retention.default.
      0 (or not set) means no maximum is specified.
    example: 1000

  default_task_cpu_limit:
    description: |
      Default limit for cpu shares used per task. This can be overridden by specifying
      a different limit in the task yaml.
    example: 256
  default_task_memory_limit:
    description: |
      Default limit for memory used per task. This can be overridden by specifying
      a different limit in the task yaml.
    example: 200mb

  syslog.hostname:
    description: |
      Client hostname with which the build logs will be sent to the syslog server.
    example: atc-syslog-drainer
    default:  atc-syslog-drainer
  syslog.address:
    description: |
      Remote syslog server address with port.
    example: 0.0.0.0:514
  syslog.transport:
    description: Transport protocol for syslog messages (Currently supporting tcp, udp & tls).
    example: tcp
  syslog.drain_interval:
    description: |
      Interval over which checking is done for new build logs to send to syslog server (duration measurement units are s/m/h)
    example: 30s
    default: 30s
  syslog.ca_cert:
    type: certificate
    description: |
      A PEM-encoded CA cert to use to verify the Syslog server SSL cert.