inlineManifests and extraManifests

Learn what inlineManifests and extraManifests are, how they differ, and why they matter.

inlineManifests and extraManifests are Talos machine configuration fields that let you automatically apply Kubernetes resources to your cluster during the initial bootstrap.

This guide explains how to use these fields to apply Kubernetes resources to Talos clusters that aren’t managed by Omni. If you’re using Omni, use Omni manifest sync instead. See Applying manifests on Omni below for more information.

Both fields are useful for automating the provisioning of components such as CNIs and other static infrastructure. However, they differ in how the manifest content is sourced and applied.

Because these fields are intended for resources that are provisioned during bootstrap, they aren’t suitable for applications or services that change frequently. For those workloads, use a GitOps or CI/CD tool instead.

inlineManifests

inlineManifests embed Kubernetes resources directly in the machine configuration. The manifest content lives alongside the rest of your config, making it ideal for tightly coupled resources that need to be provisioned as soon as the node boots up.

Here’s an example of how to configure a cluster using an inlineManifest:

apiVersion: v1alpha1
kind: KubeInlineManifestConfig
name: my-app
manifest: |
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: my-application
  spec:
    # ... deployment specification

Each inline manifest is its own KubeInlineManifestConfig document; add more by separating documents with ---.

On Talos versions earlier than v1.14, use the older configuration field:

cluster:
  inlineManifests:
    - name: my-app
      contents: |
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: my-application
        spec:
          # ... deployment specification

extraManifests

extraManifests are Kubernetes manifests hosted at external HTTP sources such as GitHub, raw file servers, or gists. Rather than carrying the content itself, the configuration points to a URL that the node fetches during bootstrap, which makes them well suited for shared, versioned, or centrally managed resources.

Because the content is fetched over the network, the node needs access to the endpoint hosting it. If the node can’t reach the endpoint, or the endpoint is down or returns an error, the manifest won’t be applied and the machine configuration will fail.

Here’s how to reference extraManifests:

apiVersion: v1alpha1
kind: KubeExternalManifestConfig
name: example-manifest
url: "https://raw.githubusercontent.com/example/repo/main/manifest.yaml"
---
apiVersion: v1alpha1
kind: KubeExternalManifestConfig
name: example-gist
url: "https://gist.githubusercontent.com/user/gist-id/raw/manifest.yaml"

Each external manifest is its own KubeExternalManifestConfig document with a name and url. To send HTTP headers when downloading (the successor to extraManifestHeaders), add an optional headers map:

apiVersion: v1alpha1
kind: KubeExternalManifestConfig
name: private-manifest
url: "https://example.com/manifest.yaml"
headers:
  Authorization: "Bearer <token>"

On Talos versions earlier than v1.14, use the older configuration field:

cluster:
  extraManifests:
    - "https://raw.githubusercontent.com/example/repo/main/manifest.yaml"
    - "https://gist.githubusercontent.com/user/gist-id/raw/manifest.yaml"

Resource ordering considerations

Talos automatically sorts all manifests, including inlineManifests, extraManifests, and built-in manifests (such as the kubelet bootstrap token and CoreDNS), before applying them in the following order:

1. Namespace resources
2. CustomResourceDefinitions (CRDs)
3. All other resources, sorted alphabetically by their metadata.name property

Example use case: Install a GitOps controller with extraManifests

A common use case for inlineManifests or extraManifests is to install a GitOps controller like Flux or ArgoCD. Once the controller is running, it connects to your Git repository and automatically applies the rest of your Kubernetes configuration.

Here’s how to install the Flux GitOps controller using an extraManifest on a Talos-native cluster. If you’re using Omni, follow the Installation on Omni section of the Flux guide instead, it uses Omni’s manifest sync and includes a namespace-injection step this walkthrough doesn’t cover, which manifest sync requires.

1. Create a patch file named flux-extra-manifest.yaml that automatically downloads and applies the Flux installation manifest from GitHub:

   cat << EOF > flux-extra-manifest.yaml
   # for talos v1.14+    
   apiVersion: v1alpha1
   kind: KubeExternalManifestConfig
   name: flux
   url: "https://github.com/fluxcd/flux2/releases/latest/download/install.yaml"
   EOF
   

2. Create a CP_IPS variable that contains the IP addresses of your control plane nodes:

   CP_IPS="<control-plane-ip-1>,<control-plane-ip-2>,<control-plane-ip-3>"
   

3. Run this command to export your TALOSCONFIG variable. You can skip this step if you’ve already done it:

   mkdir -p ~/.talos
   cp ./talosconfig ~/.talos/config
   

4. Apply the flux-extra-manifest.yaml patch to your control plane nodes:

   talosctl patch machineconfig \
   --patch @flux-extra-manifest.yaml \
   --endpoints $CP_IPS \
   --nodes $CP_IPS
   

5. Wait a few seconds and check for the Flux pods:

   kubectl get pods -n flux-system -w
   

Applying manifests on Omni

For most manifest use cases on Omni, Omni manifest sync is the recommended approach. Unlike inlineManifests and extraManifests, which are part of the per-machine Talos configuration, manifest sync is a cluster-wide Omni resource that Omni applies and reconciles directly, independent of machine configuration.

Alternatively, you can also apply inlineManifests or extraManifests patches to Talos clusters managed by Omni, the same way you’d patch any other machine configuration field. Refer to Create a Patch for Cluster Machines to learn how to create and apply the patches.

Summary: inlineManifests vs extraManifests

Here’s a quick overview of the key differences between inlineManifests and extraManifests:

	inlineManifests	extraManifests
Source	Defined directly in the machine configuration	Pulled from external URLs (GitHub, web servers, or gists)
Usecase	Early bootstrapping of critical resources	For reusable, version-controlled, or shared manifests
Benefits	No external dependencies	Centrally managed
Disadvantages	Difficult to maintain and format embedded YAML	Requires external HTTP server

How Talos handles manifest resources

Talos reconciles manifests on every boot, on every failure to apply, and on every change to the manifests in the machine config. When processing your inlineManifests and extraManifests, Talos follows a conservative, additive-only approach.

This means that Talos automatically only creates new resources. Once created, Talos never edits or deletes resources, even if they are modified or removed from the machine configuration.

If you need to prune unwanted resources (supported from Talos v1.13 onward) or update the resources, use the Kubernetes upgrade process. Specify the same Kubernetes version that’s currently running in your cluster to skip performing a Kubernetes version upgrade and only synchronize manifests.