> ## Documentation Index > Fetch the complete documentation index at: https://docs.kubox.ai/llms.txt > Use this file to discover all available pages before exploring further. # kubox cluster configuration reference > The document a cluster is built from -- the -f file of kubox cluster create and the configYAML of a Cluster resource The document a cluster is built from -- the `-f` file of `kubox cluster create` and the `configYAML` of a Cluster resource. Its shape is `internal/model.Config`, the type that parses it. Every field, from `internal/model.Config`'s `yaml` tags and doc comments. A field this document does not list is ignored rather than reported, so check each name against this list -- a misspelled key is silently dropped, not applied. ## Config AppAuth puts the console's sign-in in front of every route this gateway serves. AuthoriseURL is the console endpoint the gateway asks about each request, e.g. [https://app.kubox.cloud/api/gateway/authorize](https://app.kubox.cloud/api/gateway/authorize) HostSubdomains are the names this gateway serves, each one label under the gateway hostname: \["app", "urban"] is served at app.\ and urban.\. "@" is the gateway hostname itself, and needs a Routes entry because it has no name to default a backend from. "staging" or "production" Routes overrides the backend for a host-subdomain. By default a subdomain routes to Service \:80 in the gateway namespace ("kubox"). ModelGrant passes the console's model grant to this route's backend. Turn it on only for an app that spends its own users' model access; any other app is safer never seeing one, since whoever holds a grant can open a model session as that user. Needs appAuth, which is what asks the console for the grant in the first place. backend Service namespace; cross-namespace refs get a ReferenceGrant backend Service port backend Service name Gateway API duration, e.g. "300s"; applied to both request and backendRequest InstanceMetadata is how the nodes' IMDS answers pods. Unset leaves AWS's defaults, under which any pod can read the node's credentials. PodAccess is "blocked" or empty (AWS defaults). AwsIAMInstanceProfile is the IAM instance profile this group's nodes launch with. Empty means the cloud connection's node profile on a cluster built through one, and no profile on a laptop build; "none" means no profile either way. Pool names this group of workers as a pool that grows and shrinks with demand. Count is how many workers it starts with. Set its smallest and largest size on the cluster's node pools; changing those takes effect without a rebuild. Adding, removing or renaming a pool here rebuilds the cluster. SpotInstance defaults to true, so a node group is spot unless it opts out with spotInstance: "false". SystemExtensions are Talos system extensions baked into this group's boot image, e.g. "siderolabs/gvisor". Whether to create a subdomain record Optional, defaults to cluster short name Maps each key in the created Secret to a key inside the AWS JSON secret. Empty copies the whole value. Name of the secret in AWS Secrets Manager. Name of the Kubernetes Secret. Defaults to the AWS key. Namespace the Kubernetes Secret is created in. Defaults to "default". Kind of Kubernetes Secret to create: generic, docker-registry, or tls. Pool names this group of workers as a pool that grows and shrinks with demand. Count is how many workers it starts with. Set its smallest and largest size on the cluster's node pools; changing those takes effect without a rebuild. Adding, removing or renaming a pool here rebuilds the cluster. SystemExtensions are Talos system extensions baked into this group's boot image, e.g. "siderolabs/gvisor". Config holds controller-specific configuration options. Enabled determines whether this controller should be installed. Defaults to true. Name identifies this entry. It is also the controller to install unless Type says otherwise, so an entry naming a controller directly keeps working. RoleBindings declare ClusterRoleBindings to apply alongside this controller. The subject is a Kubernetes Group (e.g., a Teleport team group). Name is the ClusterRoleBinding name. Role is the ClusterRole name referenced by the binding. TeleportGroup is the Kubernetes Group subject that receives the role. Type is the controller implementation to install. It defaults to Name, and lets a cluster run two instances of one controller under different names -- an nvidia and a gVisor RuntimeClass, say. e.g., "kubox.cloud" Identity makes this cluster trust a console, so kubectl works with the same sign-in as everything else. Absent means it trusts nobody and the sealed admin kubeconfig remains the only way in. Audience the token must name. Defaults to kubox-cluster:\. CABundle validates the discovery fetch, when the serving certificate is not one the node already trusts. Empty means the in-cluster mirror is served by a certificate from the cluster's own CA. DiscoveryURL is where THIS cluster fetches the issuer's keys. Defaults to the in-cluster mirror, which is what almost every deployment should use. GroupBindings grants a ClusterRole to everyone in a group, so access belongs to an organisation rather than a person and removing someone there removes it here. ClusterRole is an existing role: view, edit, cluster-admin, or your own. Group is the claim value, normally `:`. GroupsClaim carries organisation membership. Defaults to groups. IssuerURL is what the `iss` claim in a token says, and must match it exactly. UsernameClaim identifies the person. Defaults to email. Pulumi identifies where the cluster's infrastructure state is stored: which organisation and project it is kept under, and its location. destination key -> source key; empty copies every key as-is data key -> environment variable that seeds it data key -> generator (hex16, hex32, alnum16, alnum32, uuid) defaults to "default"; created if missing ## All types Every type in the document, in the order the root reaches them. Each is also linked from the field that uses it above. ### ConfigApps ### AwsConfig See [IngressConfig](#ingressconfig). InstanceMetadata is how the nodes' IMDS answers pods. Unset leaves AWS's defaults, under which any pod can read the node's credentials. See [InstanceMetadataConfig](#instancemetadataconfig). See [AwsNodeGroup](#awsnodegroup). See [Route53Config](#route53config). See [AwsSecret](#awssecret). ### AzureConfig See [AzureNodeGroup](#azurenodegroup). ### ControllerConfig ControllerConfig holds the configuration for a system controller. Config holds controller-specific configuration options. Enabled determines whether this controller should be installed. Defaults to true. Name identifies this entry. It is also the controller to install unless Type says otherwise, so an entry naming a controller directly keeps working. RoleBindings declare ClusterRoleBindings to apply alongside this controller. The subject is a Kubernetes Group (e.g., a Teleport team group). See [RoleBinding](#rolebinding). Type is the controller implementation to install. It defaults to Name, and lets a cluster run two instances of one controller under different names -- an nvidia and a gVisor RuntimeClass, say. ### DNSConfig DNSConfig configures global DNS settings. e.g., "kubox.cloud" ### ConfigGitOps See [WaitForCRD](#waitforcrd). ### IdentityConfig IdentityConfig makes a cluster trust a console, so a person can use kubectl with the same sign-in they use everywhere else. Audience the token must name. Defaults to kubox-cluster:\. CABundle validates the discovery fetch, when the serving certificate is not one the node already trusts. Empty means the in-cluster mirror is served by a certificate from the cluster's own CA. DiscoveryURL is where THIS cluster fetches the issuer's keys. Defaults to the in-cluster mirror, which is what almost every deployment should use. GroupBindings grants a ClusterRole to everyone in a group, so access belongs to an organisation rather than a person and removing someone there removes it here. See [GroupBinding](#groupbinding). GroupsClaim carries organisation membership. Defaults to groups. IssuerURL is what the `iss` claim in a token says, and must match it exactly. UsernameClaim identifies the person. Defaults to email. ### Metadata Pulumi identifies where the cluster's infrastructure state is stored: which organisation and project it is kept under, and its location. See [MetadataPulumi](#metadatapulumi). ### RbacRole RbacRole is a declarative ClusterRole definition loaded from the cluster config. See [RbacPolicyRule](#rbacpolicyrule). ### SecretsConfig SecretsConfig declares secrets kubox itself materialises at create time, as opposed to aws.secrets which are fetched from AWS Secrets Manager. See [GeneratedSecret](#generatedsecret). ### ConfigTags ### ConfigTalos See [Machine](#machine). ### IngressConfig IngressConfig configures internet ingress through the load balancer. AppAuth puts the console's sign-in in front of every route this gateway serves. See [AppAuthConfig](#appauthconfig). HostSubdomains are the names this gateway serves, each one label under the gateway hostname: \["app", "urban"] is served at app.\ and urban.\. "@" is the gateway hostname itself, and needs a Routes entry because it has no name to default a backend from. "staging" or "production" Routes overrides the backend for a host-subdomain. By default a subdomain routes to Service \:80 in the gateway namespace ("kubox"). See [IngressRoute](#ingressroute). ### InstanceMetadataConfig InstanceMetadataConfig is the IMDS boundary on a node. PodAccess is "blocked" or empty (AWS defaults). ### AwsNodeGroup AwsNodeGroup extends NodeGroup with AWS-specific configuration. AwsIAMInstanceProfile is the IAM instance profile this group's nodes launch with. Empty means the cloud connection's node profile on a cluster built through one, and no profile on a laptop build; "none" means no profile either way. Pool names this group of workers as a pool that grows and shrinks with demand. Count is how many workers it starts with. Set its smallest and largest size on the cluster's node pools; changing those takes effect without a rebuild. Adding, removing or renaming a pool here rebuilds the cluster. SpotInstance defaults to true, so a node group is spot unless it opts out with spotInstance: "false". SystemExtensions are Talos system extensions baked into this group's boot image, e.g. "siderolabs/gvisor". See [Taint](#taint). ### Route53Config Route53Config configures AWS Route53 DNS record creation. Whether to create a subdomain record Optional, defaults to cluster short name ### AwsSecret AwsSecret pulls a secret from AWS Secrets Manager into the cluster. Maps each key in the created Secret to a key inside the AWS JSON secret. Empty copies the whole value. Name of the secret in AWS Secrets Manager. Name of the Kubernetes Secret. Defaults to the AWS key. Namespace the Kubernetes Secret is created in. Defaults to "default". Kind of Kubernetes Secret to create: generic, docker-registry, or tls. ### AzureNodeGroup AzureNodeGroup extends NodeGroup with Azure-specific configuration. Pool names this group of workers as a pool that grows and shrinks with demand. Count is how many workers it starts with. Set its smallest and largest size on the cluster's node pools; changing those takes effect without a rebuild. Adding, removing or renaming a pool here rebuilds the cluster. SystemExtensions are Talos system extensions baked into this group's boot image, e.g. "siderolabs/gvisor". See [Taint](#taint). ### RoleBinding RoleBinding is a declarative ClusterRoleBinding that grants a role to a group. Name is the ClusterRoleBinding name. Role is the ClusterRole name referenced by the binding. TeleportGroup is the Kubernetes Group subject that receives the role. ### WaitForCRD ### GroupBinding GroupBinding grants a ClusterRole to everyone in a group. ClusterRole is an existing role: view, edit, cluster-admin, or your own. Group is the claim value, normally `:`. ### MetadataPulumi ### RbacPolicyRule RbacPolicyRule mirrors the fields of a Kubernetes rbacv1.PolicyRule. ### GeneratedSecret GeneratedSecret is a Secret whose values are created once, on first `kubox admin create`, and then left alone: a value that already exists in the cluster is never regenerated, so re-running create (or rotating by hand) does not break anything that holds the old value. Copies are always re-synced from the primary so they cannot drift. See [SecretCopy](#secretcopy). data key -> environment variable that seeds it data key -> generator (hex16, hex32, alnum16, alnum32, uuid) defaults to "default"; created if missing ### Machine See [KubeletConfig](#kubeletconfig). ### AppAuthConfig AppAuthConfig makes the gateway ask the console who somebody is before an app behind it sees the request. AuthoriseURL is the console endpoint the gateway asks about each request, e.g. [https://app.kubox.cloud/api/gateway/authorize](https://app.kubox.cloud/api/gateway/authorize) ### IngressRoute IngressRoute overrides where a host-subdomain's HTTPRoute sends traffic. Every field is optional; an unset field keeps the default (Service named after the subdomain, gateway namespace, port 80, gateway default timeout). ModelGrant passes the console's model grant to this route's backend. Turn it on only for an app that spends its own users' model access; any other app is safer never seeing one, since whoever holds a grant can open a model session as that user. Needs appAuth, which is what asks the console for the grant in the first place. backend Service namespace; cross-namespace refs get a ReferenceGrant backend Service port backend Service name Gateway API duration, e.g. "300s"; applied to both request and backendRequest ### Taint ### SecretCopy SecretCopy mirrors keys of a GeneratedSecret into another Secret, typically in another namespace, because Kubernetes Secrets are namespaced. destination key -> source key; empty copies every key as-is ### KubeletConfig KubeletConfig represents the kubelet configuration. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.