Skip to content

docs: document the three gateway.* host-delegation keys in the platform-package reference #688

Description

@mattia-eleuteri

The platform-package reference page is a hand-written table of the spec.components.platform.values.* keys, so new keys in packages/core/platform/values.yaml do not reach it automatically. The platform chart has no values.schema.json, so nothing on this path is generated.

A change in progress upstream (design proposal: cozystack/community#70) adds three keys under gateway:, all defaulting to inert:

Key Type Default What it does
gateway.reservedHosts []string [] Hostname suffixes the platform never delegates to a tenant. A tenant may not set Tenant.spec.host to one of these or to a subdomain of one, even when its allowlist would otherwise cover it. Cluster-admins are unaffected. This is the platform owner's veto and the backstop against a faulty grant.
gateway.hostGrantGroups []string [] Kubernetes group names allowed to write Tenant.spec.allowedHosts, in addition to system:masters and the cozy-* service accounts — e.g. system:serviceaccounts:my-api. A namespace-wide group trusts every service account in that namespace, present and future. These accounts grant domains; they do not gain the ability to set spec.host themselves.
gateway.tenantHostDelegation bool false Seeds each tenant's own apex into its allowlist, so a tenant may set spec.host anywhere under the hostname already delegated to it. Off by default: enabling it grants every tenant a capability it did not have.

Worth documenting alongside the table: hostGrantGroups is unsafe unless reservedHosts covers the platform's own hostnames, since otherwise a grant account can delegate the platform apex to a tenant whose subtenant then claims it.

Raised from the downstream trigger map in docs/agents/contributing.md; filing as an issue rather than a PR because the upstream design has not been discussed yet and the key names could still change in review.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions