Archive

The archive resource downloads and extracts archives from HTTP/HTTPS URLs. It supports tar.gz, tgz, tar, and zip formats.

- archive:
    - /opt/downloads/app-v1.2.3.tar.gz:
        url: https://releases.example.com/app/v1.2.3/app-v1.2.3.tar.gz
        checksum: "a1b2c3d4e5f6..."
        extract_parent: /opt/app
        creates: /opt/app/bin/app
        owner: app
        group: app
        cleanup: true

ccm ensure archive /opt/downloads/app.tar.gz \
    --url https://releases.example.com/app.tar.gz \
    --extract-parent /opt/app \
    --creates /opt/app/bin/app \
    --owner root --group root

{
  "protocol": "io.choria.ccm.v1.resource.ensure.request",
  "type": "archive",
  "properties": {
    "name": "/opt/downloads/app-v1.2.3.tar.gz",
    "url": "https://releases.example.com/app/v1.2.3/app-v1.2.3.tar.gz",
    "checksum": "a1b2c3d4e5f6...",
    "extract_parent": "/opt/app",
    "creates": "/opt/app/bin/app",
    "owner": "app",
    "group": "app",
    "cleanup": true
  }
}

This downloads the archive, extracts it to /opt/app, and removes the archive file after extraction. Future runs skip the download if /opt/app/bin/app exists.

Ensure Values

Properties

Authentication

The archive resource supports two authentication methods:

Basic Authentication:

- archive:
    - /opt/downloads/private-app.tar.gz:
        url: https://private.example.com/app.tar.gz
        username: deploy
        password: "{{ lookup('data.deploy_password') }}"
        extract_parent: /opt/app
        owner: root
        group: root

ccm ensure archive /opt/downloads/private-app.tar.gz \
    --url https://private.example.com/app.tar.gz \
    --username deploy \
    --password "{{ lookup('data.deploy_password') }}"

{
  "protocol": "io.choria.ccm.v1.resource.ensure.request",
  "type": "archive",
  "properties": {
    "name": "/opt/downloads/private-app.tar.gz",
    "url": "https://private.example.com/app.tar.gz",
    "username": "deploy",
    "password": "secret",
    "extract_parent": "/opt/app",
    "owner": "root",
    "group": "root"
  }
}

Custom Headers:

- archive:
    - /opt/downloads/app.tar.gz:
        url: https://api.example.com/releases/app.tar.gz
        headers:
          Authorization: "Bearer {{ lookup('data.api_token') }}"
          X-Custom-Header: custom-value
        extract_parent: /opt/app
        owner: root
        group: root

ccm ensure archive /opt/downloads/app.tar.gz \
    --url https://api.example.com/releases/app.tar.gz \
    --headers "Authorization:{{ lookup('data.api_token') }}"

{
  "protocol": "io.choria.ccm.v1.resource.ensure.request",
  "type": "archive",
  "properties": {
    "name": "/opt/downloads/app.tar.gz",
    "url": "https://api.example.com/releases/app.tar.gz",
    "headers": {
      "Authorization": "Bearer mytoken",
      "X-Custom-Header": "custom-value"
    },
    "extract_parent": "/opt/app",
    "owner": "root",
    "group": "root"
  }
}

Idempotency

The archive resource is idempotent through multiple mechanisms:

1. Checksum verification: If a checksum is provided and the existing file matches, no download occurs.
2. Creates file: If creates is specified and that file exists, neither download nor extraction occurs.
3. File existence: If the archive file exists with matching checksum and owner/group, no changes are made.

For best idempotency, always specify either checksum or creates (or both).

Cleanup Behavior

When cleanup: true is set:

• The archive file is deleted after successful extraction
• The extract_parent property is required
• The creates property is required to track extraction state across runs

Supported Archive Formats

Exec

The exec resource executes commands to bring the system into the desired state. It is idempotent when used with the creates property or refreshonly mode.

- exec:
    - /usr/bin/touch /tmp/hello:
        creates: /tmp/hello
        timeout: 30s
        cwd: /tmp

- exec:
    - touch_hello:
        command: /usr/bin/touch /tmp/hello
        creates: /tmp/hello
        timeout: 30s
        cwd: /tmp

ccm ensure exec "/usr/bin/touch /tmp/hello" --creates /tmp/hello --timeout 30s

{
  "protocol": "io.choria.ccm.v1.resource.ensure.request",
  "type": "exec",
  "properties": {
    "name": "/usr/bin/touch /tmp/hello",
    "creates": "/tmp/hello",
    "timeout": "30s",
    "cwd": "/tmp"
  }
}

The command runs only if /tmp/hello does not exist.

Providers

The exec resource supports two providers:

The posix provider is the default and is suitable for most commands. Use the shell provider when you need shell features:

- exec:
    - cleanup-logs:
        command: find /var/log -name '*.log' -mtime +30 -delete && echo "Done"
        provider: shell

    - check-service:
        command: systemctl is-active httpd || systemctl start httpd
        provider: shell

    - process-data:
        command: cat /tmp/input.txt | grep -v '^#' | sort | uniq > /tmp/output.txt
        provider: shell

Properties

File

The file resource manages files and directories, including their content, ownership, and permissions.

- file:
    - /etc/motd:
        ensure: present
        content: |
          Managed by CCM {{ now() }}
        owner: root
        group: root
        mode: "0644"

ccm ensure file /etc/motd --source /tmp/ccm/motd --owner root --group root --mode 0644

{
  "protocol": "io.choria.ccm.v1.resource.ensure.request",
  "type": "file",
  "properties": {
    "name": "/etc/motd",
    "ensure": "present",
    "content": "Managed by CCM\n",
    "owner": "root",
    "group": "root",
    "mode": "0644"
  }
}

This copies the contents of /tmp/ccm/motd to /etc/motd verbatim and sets ownership.

Use --content or --content-file to parse content through the template engine before writing.

Ensure Values

Properties

Package

The package resource manages system packages. Specify whether the package should be present, absent, at the latest version, or at a specific version.

- package:
    - zsh:
        ensure: "5.9"

ccm ensure package zsh 5.9

{
  "protocol": "io.choria.ccm.v1.resource.ensure.request",
  "type": "package",
  "properties": {
    "name": "zsh",
    "ensure": "5.9"
  }
}

Ensure Values

Properties

Provider Notes

APT (Debian/Ubuntu)

The APT provider preserves existing configuration files during package installation and upgrades. When a package is upgraded and the maintainer has provided a new version of a configuration file, the existing file is kept (--force-confold behavior).

Packages in a partially installed or config-files state (removed but configuration remains) are treated as absent. Reinstalling such packages will preserve the existing configuration files.

The provider runs non-interactively and suppresses prompts from apt-listbugs and apt-listchanges.

Scaffold

The scaffold resource renders files from a source template directory to a target directory. Templates have access to facts and Hiera data, enabling dynamic configuration generation from directory structures.

- scaffold:
    - /etc/app:
        ensure: present
        source: templates/app
        engine: jet
        purge: true

ccm ensure scaffold /etc/app templates/app --engine jet --purge

{
  "protocol": "io.choria.ccm.v1.resource.ensure.request",
  "type": "scaffold",
  "properties": {
    "name": "/etc/app",
    "ensure": "present",
    "source": "templates/app",
    "engine": "jet",
    "purge": true
  }
}

This renders templates from the templates/app directory into /etc/app using the Jet template engine, removing any files in the target not present in the source.

Ensure Values

Properties

Template Engines

Two template engines are supported:

The engine defaults to jet if not specified. Delimiters can be customized via left_delimiter and right_delimiter.

Custom Delimiters

- scaffold:
    - /etc/myservice:
        ensure: present
        source: templates/myservice
        engine: go
        left_delimiter: "<<"
        right_delimiter: ">>"

ccm ensure scaffold /etc/myservice templates/myservice \
    --engine go --left-delimiter "<<" --right-delimiter ">>"

{
  "protocol": "io.choria.ccm.v1.resource.ensure.request",
  "type": "scaffold",
  "properties": {
    "name": "/etc/myservice",
    "ensure": "present",
    "source": "templates/myservice",
    "engine": "go",
    "left_delimiter": "<<",
    "right_delimiter": ">>"
  }
}

Post-Processing

The post property defines commands to run on rendered files. Each entry is a map where the key is a glob pattern matched against the file’s basename and the value is a command to execute. Use {} in the command as a placeholder for the file’s full path; if omitted, the path is appended as the last argument.

- scaffold:
    - /opt/app:
        ensure: present
        source: templates/app
        post:
          - "*.go": "go fmt {}"
          - "*.sh": "chmod +x {}"

ccm ensure scaffold /opt/app templates/app \
    --post "*.go"="go fmt {}" --post "*.sh"="chmod +x {}"

{
  "protocol": "io.choria.ccm.v1.resource.ensure.request",
  "type": "scaffold",
  "properties": {
    "name": "/opt/app",
    "ensure": "present",
    "source": "templates/app",
    "post": [
      {"*.go": "go fmt {}"},
      {"*.sh": "chmod +x {}"}
    ]
  }
}

Post-processing runs immediately after each file is rendered. Files skipped due to skip_empty are not post-processed.

Purge Behavior

When purge: true is set, files in the target directory that are not present in the source template directory are deleted during rendering. In noop mode, these deletions are logged but not performed.

When purge is disabled (the default), files not present in the source are tracked but not removed. They do not affect idempotency checks for ensure: present, meaning the resource is considered stable even if extra files exist in the target.

Removal Behavior

When ensure: absent, only managed files (changed and stable) are removed. Files not belonging to the scaffold (purged files) are left untouched. After removing managed files and empty subdirectories, the target directory itself is removed on a best-effort basis — it is only deleted if empty. If unrelated files remain, the directory is preserved and no error is raised.

Idempotency

The scaffold resource determines idempotency by rendering templates in noop mode and comparing results against the target directory.

For ensure: present:

• Changed files: Files that would be created or modified. Any changed files make the resource unstable.
• Stable files: Files whose content matches the rendered output. At least one stable file must exist for the resource to be considered stable.
• Purged files: Files in the target not present in the source. These only affect stability when purge is enabled.

For ensure: absent, the status check filters Changed and Stable lists to only include files that actually exist on disk. This means after a successful removal, the scaffold is considered absent even if the target directory still exists with unrelated files. Purged files never affect the absent stability check.

Source Resolution

The source property is resolved relative to the manager’s working directory when it is a relative path. URL sources (with a scheme) are passed through unchanged. This allows manifests bundled with template directories to use relative paths.

Template Environment

Templates receive the full template environment, which provides access to:

• facts - System facts for the managed node
• data - Hiera-resolved configuration data
• Template helper functions

Creating Scaffolds

A scaffold source is a directory tree where every file is a template. The directory structure is mirrored directly into the target, so the source layout becomes the output layout.

Source Directory Structure

templates/app/
├── _partials/
│   └── header.conf
├── config.yaml
├── scripts/
│   └── setup.sh
└── README.md

This renders into:

/etc/app/
├── config.yaml
├── scripts/
│   └── setup.sh
└── README.md

The _partials directory is special — its contents are available to templates but are never copied to the target.

Template Syntax

Every file in the source directory is processed as a template. The syntax depends on the engine selected.

Jet engine (default, [[ / ]] delimiters):

# config.yaml
hostname: [[ facts.hostname ]]
environment: [[ data.environment ]]
workers: [[ data.worker_count ]]

Go engine ({{ / }} delimiters):

# config.yaml
hostname: {{ .facts.hostname }}
environment: {{ .data.environment }}
workers: {{ .data.worker_count }}

The Jet engine is the default because its [[ / ]] delimiters avoid conflicts with configuration files that use curly braces (YAML, JSON, systemd units). Use the Go engine when you need access to Sprig functions.

Partials

Files inside a _partials directory are reusable template fragments. They are rendered on demand using the render function but are excluded from the output.

This is useful for shared headers, repeated configuration blocks, or any content used across multiple files.

Jet:

[[ render("_partials/header.conf", .) ]]

server {
    listen [[ data.port ]];
}

Go:

{{ render "_partials/header.conf" . }}

server {
    listen {{ .data.port }};
}

Built-in Functions

Two functions are available in both template engines:

render evaluates another template file from the source directory and returns its output as a string. The partial is rendered using the same engine and data as the calling template.

[[ render("_partials/database.conf", .) ]]

{{ render "_partials/database.conf" . }}

write creates an additional file in the target directory from within a template. This is useful for dynamically generating files based on data — for example, creating one configuration file per service.

[[ write("extra.conf", "generated content") ]]

{{ write "extra.conf" "generated content" }}

Sprig Functions

When using the Go template engine, all Sprig template functions are available. These provide string manipulation, math, date formatting, list operations, and more:

# Go engine example with Sprig functions
hostname: {{ .facts.hostname | upper }}
packages: {{ join ", " .data.packages }}
generated: {{ now | date "2006-01-02" }}

Example Scaffold

A complete scaffold for an application configuration:

Source structure:

templates/myapp/
├── _partials/
│   └── logging.conf
├── myapp.conf
└── scripts/
    └── healthcheck.sh

_partials/logging.conf (Jet):

log_level = [[ data.log_level ]]
log_file = /var/log/myapp/[[ facts.hostname ]].log

myapp.conf (Jet):

[[ render("_partials/logging.conf", .) ]]

[server]
bind = 0.0.0.0
port = [[ data.port ]]
workers = [[ data.workers ]]

scripts/healthcheck.sh (Jet):

#!/bin/bash
curl -sf http://localhost:[[ data.port ]]/health || exit 1

Manifest using this scaffold:

- scaffold:
    - /etc/myapp:
        ensure: present
        source: templates/myapp
        purge: true
        post:
          - "*.sh": "chmod +x {}"

With facts {"hostname": "web01"} and data {"port": 8080, "workers": 4, "log_level": "info"}, this renders:

/etc/myapp/
├── myapp.conf
└── scripts/
    └── healthcheck.sh

Where myapp.conf contains:

log_level = info
log_file = /var/log/myapp/web01.log

[server]
bind = 0.0.0.0
port = 8080
workers = 4

Service

The service resource manages system services. Services have two independent properties: whether they are running and whether they are enabled to start at boot.

Services can subscribe to other resources and restart when those resources change.

- service:
    - httpd:
        ensure: running
        enable: true
        subscribe:
          - package#httpd

ccm ensure service httpd running --enable --subscribe package#httpd

{
  "protocol": "io.choria.ccm.v1.resource.ensure.request",
  "type": "service",
  "properties": {
    "name": "httpd",
    "ensure": "running",
    "enable": true,
    "subscribe": ["package#httpd"]
  }
}

Ensure Values

If ensure is not specified, it defaults to running.

Properties

JSON API

CCM provides a STDIN/STDOUT API for managing resources programmatically. This enables integration with external languages, allowing you to build DSLs in Ruby, Perl, Python, or any language that can execute processes and handle JSON or YAML.

Overview

The API uses a simple request/response pattern:

1. Send a request to ccm ensure api pipe via STDIN
2. Receive a response on STDOUT

Both JSON and YAML formats are supported for requests. The response format is always JSON, but can be explicitly set to YAML using --yaml.

Command

ccm ensure api pipe [--yaml] [--noop] [--facts <file>] [--data <file>]

Request Format

Requests must include a protocol identifier, resource type, and properties.

JSON Request

{
  "protocol": "io.choria.ccm.v1.resource.ensure.request",
  "type": "package",
  "properties": {
    "name": "nginx",
    "ensure": "present"
  }
}

YAML Request

protocol: io.choria.ccm.v1.resource.ensure.request
type: package
properties:
  name: nginx
  ensure: present

Request Fields

Response Format

Responses include a protocol identifier and either a state object (on success) or an error message.

For the full response structure, see ResourceEnsureApiResponse in the Go documentation. The state field contains a TransactionEvent.

Successful Response

{
  "protocol": "io.choria.ccm.v1.resource.ensure.response",
  "state": {
    "protocol": "io.choria.ccm.v1.transaction.event",
    "event_id": "2abc123def456",
    "timestamp": "2026-01-28T10:30:00Z",
    "type": "package",
    "provider": "dnf",
    "name": "nginx",
    "requested_ensure": "present",
    "final_ensure": "1.24.0-1.el9",
    "duration": 1500000000,
    "changed": true,
    "failed": false
  }
}

Error Response

{
  "protocol": "io.choria.ccm.v1.resource.ensure.response",
  "error": "invalid protocol \"wrong.protocol\""
}

Examples

Install a Package

echo '{
  "protocol": "io.choria.ccm.v1.resource.ensure.request",
  "type": "package",
  "properties": {
    "name": "htop",
    "ensure": "present"
  }
}' | ccm ensure api pipe

Manage a Service

cat <<EOF | ccm ensure api pipe
protocol: io.choria.ccm.v1.resource.ensure.request
type: service
properties:
  name: nginx
  ensure: running
EOF

Create a File

echo '{
  "protocol": "io.choria.ccm.v1.resource.ensure.request",
  "type": "file",
  "properties": {
    "name": "/etc/motd",
    "ensure": "present",
    "content": "Welcome to this server\n",
    "owner": "root",
    "group": "root",
    "mode": "0644"
  }
}' | ccm ensure api pipe

Dry-Run Mode

echo '{
  "protocol": "io.choria.ccm.v1.resource.ensure.request",
  "type": "package",
  "properties": {
    "name": "vim",
    "ensure": "absent"
  }
}' | ccm ensure api pipe --noop

Resource Types

For detailed information about each resource type and its properties, see the Resource Documentation

CLI Plugins

CCM supports extending the CLI with custom commands using App Builder. This allows you to create organization-specific workflows that integrate with the ccm command.

Plugin Locations

CCM searches for plugins in two directories:

Plugins in the user directory override system plugins with the same name.

Plugin File Format

Plugin files must be named <command>-plugin.yaml. The filename determines the command name:

deploy-plugin.yaml    → ccm deploy
backup-plugin.yaml    → ccm backup
myapp-plugin.yaml     → ccm myapp

Basic Plugin Structure

Plugins use App Builder’s YAML definition format. Here’s a minimal example:

# deploy-plugin.yaml
name: deploy
description: Deploy application configuration
commands:
  - name: web
    description: Deploy web server configuration
    type: exec
    command: |
      ccm apply /etc/ccm/manifests/webserver.yaml

This creates ccm deploy web which applies a manifest.

Passing Data to Manifests

Plugins can pass data to manifests through environment variables or facts. Both are accessible in manifest templates.

Using Environment Variables

Environment variables set in the plugin are available in manifests via {{ lookup("env.VAR_NAME") }}:

# deploy-plugin.yaml
name: deploy
description: Deploy with environment
commands:
  - name: production
    description: Deploy to production
    type: exec
    environment:
      - "DEPLOY_ENV=production"
      - "LOG_LEVEL=warn"
    command: |
      ccm apply /etc/ccm/manifests/app.yaml

In the manifest:

resources:
  - type: file
    name: /etc/app/config.yaml
    content: |
      environment: {{ lookup("env.DEPLOY_ENV") }}
      log_level: {{ lookup("env.LOG_LEVEL") }}

Using Facts

Pass additional facts using the --fact flag. Facts are available via {{ lookup("facts.KEY") }}:

# deploy-plugin.yaml
name: deploy
description: Deploy with custom facts
commands:
  - name: app
    description: Deploy application
    type: exec
    arguments:
      - name: version
        description: Application version to deploy
        required: true
    command: |
      ccm apply /etc/ccm/manifests/app.yaml --fact app_version={{ .Arguments.version }}

In the manifest:

resources:
  - type: package
    name: myapp
    ensure: present
    version: "{{ lookup('facts.app_version') }}"

Further Reading

For complete App Builder documentation including all command types, templating features, and advanced options, see the App Builder documentation.

Since version 0.13.0 of App Builder it has a transform and a command that can invoke CCM Manifests, this combines well with flags, arguments and form wizards to create custom UI’s that manage your infrastructure.

Archive Type

This document describes the design of the archive resource type for downloading and extracting archives.

Overview

The archive resource manages remote archives with three phases:

• Download: Fetch archive from a URL to local filesystem
• Extract: Unpack archive contents to a target directory
• Cleanup: Optionally remove the archive file after extraction

These phases are conditional based on current state and configuration.

Provider Interface

Archive providers must implement the ArchiveProvider interface:

type ArchiveProvider interface {
    model.Provider

    Download(ctx context.Context, properties *model.ArchiveResourceProperties, log model.Logger) error
    Extract(ctx context.Context, properties *model.ArchiveResourceProperties, log model.Logger) error
    Status(ctx context.Context, properties *model.ArchiveResourceProperties) (*model.ArchiveState, error)
}

Method Responsibilities

Status Response

The Status method returns an ArchiveState containing:

type ArchiveState struct {
    CommonResourceState
    Metadata *ArchiveMetadata
}

type ArchiveMetadata struct {
    Name          string    // Archive file path
    Checksum      string    // SHA256 hash of archive
    ArchiveExists bool      // Whether archive file exists
    CreatesExists bool      // Whether creates marker file exists
    Owner         string    // Archive file owner
    Group         string    // Archive file group
    MTime         time.Time // Modification time
    Size          int64     // File size in bytes
    Provider      string    // Provider name (e.g., "http")
}

The Ensure field in CommonResourceState is set to:

• present if the archive file exists
• absent if the archive file does not exist

Available Providers

Ensure States

Supported Archive Formats

The URL and local file name must have matching archive type extensions.

Apply Logic

┌─────────────────────────────────────────┐
│ Get current state via Status()          │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ Is current state desired state?         │
└─────────────────┬───────────────────────┘
              Yes │         No
                  ▼         │
          ┌───────────┐     │
          │ No change │     │
          └───────────┘     │
                            ▼
              ┌─────────────────────────┐
              │ What is desired ensure? │
              └─────────────┬───────────┘
                            │
            ┌───────────────┴───────────────┐
            │ absent                        │ present
            ▼                               ▼
    ┌───────────────┐             ┌─────────────────────┐
    │ Remove archive│             │ Download needed?    │
    │ file          │             │ (checksum mismatch  │
    └───────────────┘             │  or file missing)   │
                                  └─────────┬───────────┘
                                        Yes │         No
                                            ▼         │
                                    ┌───────────┐     │
                                    │ Download  │     │
                                    └─────┬─────┘     │
                                          │           │
                                          ▼           ▼
                                  ┌─────────────────────────┐
                                  │ Extract needed?         │
                                  │ (extract_parent set AND │
                                  │  (download occurred OR  │
                                  │   creates file missing))│
                                  └─────────┬───────────────┘
                                        Yes │         No
                                            ▼         │
                                    ┌───────────┐     │
                                    │ Extract   │     │
                                    └─────┬─────┘     │
                                          │           │
                                          ▼           ▼
                                  ┌─────────────────────────┐
                                  │ Cleanup enabled?        │
                                  └─────────┬───────────────┘
                                        Yes │         No
                                            ▼         ▼
                                    ┌───────────┐ ┌───────┐
                                    │ Remove    │ │ Done  │
                                    │ archive   │ └───────┘
                                    └───────────┘

Idempotency

The archive resource uses multiple checks for idempotency:

State Checks (in order)

1. Ensure absent: Archive file must not exist
2. Creates file: If creates is set, the marker file must exist
3. Archive existence: If cleanup: false, archive must exist
4. Owner/Group: Archive file attributes must match
5. Checksum: If specified, archive checksum must match

Decision Table

Creates Property

The creates property provides idempotency for extraction:

- archive:
    - /tmp/app.tar.gz:
        url: https://example.com/app.tar.gz
        extract_parent: /opt/app
        creates: /opt/app/bin/app
        owner: root
        group: root

Behavior:

• If /opt/app/bin/app exists, skip download and extraction
• Useful when extracted files indicate successful prior extraction
• Prevents re-extraction on every run

Cleanup Property

The cleanup property removes the archive after extraction:

- archive:
    - /tmp/app.tar.gz:
        url: https://example.com/app.tar.gz
        extract_parent: /opt/app
        creates: /opt/app/bin/app
        cleanup: true
        owner: root
        group: root

Requirements:

• extract_parent must be set (cleanup only makes sense with extraction)
• creates must be set to track extraction state

Behavior:

• After successful extraction, remove the archive file
• On subsequent runs, creates file prevents re-download

Checksum Verification

When checksum is specified:

- archive:
    - /tmp/app.tar.gz:
        url: https://example.com/app.tar.gz
        checksum: "a1b2c3d4..."
        owner: root
        group: root

Behavior:

• Downloaded file is verified against SHA256 checksum
• Existing file checksum is compared to detect changes
• Checksum mismatch triggers re-download
• Download fails if fetched content doesn’t match

Authentication

Archives support two authentication methods:

Basic Authentication

- archive:
    - /tmp/app.tar.gz:
        url: https://private.example.com/app.tar.gz
        username: deploy
        password: "{{ lookup('data.password') }}"
        owner: root
        group: root

Custom Headers

- archive:
    - /tmp/app.tar.gz:
        url: https://api.example.com/releases/app.tar.gz
        headers:
          Authorization: "Bearer {{ lookup('data.token') }}"
        owner: root
        group: root

Required Properties

URL Validation

URLs are validated during resource creation:

• Must be valid URL format
• Scheme must be http or https
• Path must end with supported archive extension
• Extension must match the name property extension

Noop Mode

In noop mode, the archive type:

1. Queries current state normally
2. Computes what actions would be taken
3. Sets appropriate NoopMessage:
   • “Would have downloaded”
   • “Would have extracted”
   • “Would have cleaned up”
   • “Would have removed”
4. Reports Changed: true if changes would occur
5. Does not call provider Download/Extract methods
6. Does not remove files

Multiple actions are joined with “. " (e.g., “Would have downloaded. Would have extracted”).

Desired State Validation

After applying changes (in non-noop mode), the type verifies the archive reached the desired state by calling Status() again and checking all conditions. If validation fails, ErrDesiredStateFailed is returned.

Exec Type

This document describes the design of the exec resource type for executing commands.

Overview

The exec resource executes commands with idempotency controls:

• Creates: Skip execution if a file exists
• Refresh Only: Only execute when triggered by a subscribed resource
• Exit Codes: Validate success via configurable return codes

Provider Interface

Exec providers must implement the ExecProvider interface:

type ExecProvider interface {
    model.Provider

    Execute(ctx context.Context, properties *model.ExecResourceProperties, log model.Logger) (int, error)
    Status(ctx context.Context, properties *model.ExecResourceProperties) (*model.ExecState, error)
}

Method Responsibilities

Status Response

The Status method returns an ExecState containing:

type ExecState struct {
    CommonResourceState

    ExitCode         *int // Exit code from last execution (nil if not run)
    CreatesSatisfied bool // Whether creates file exists
}

The Ensure field in CommonResourceState is set to:

• present if the creates file exists
• absent if the creates file does not exist (or not specified)

Available Providers

Properties

Apply Logic

┌─────────────────────────────────────────┐
│ Get current state via Status()          │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ Check for subscribe refresh             │
└─────────────────┬───────────────────────┘
                  │
    ┌─────────────┴─────────────┐
    │ Subscribed resource       │
    │ changed?                  │
    └─────────────┬─────────────┘
              Yes │         No
                  ▼         │
          ┌───────────┐     │
          │ Execute   │     │
          └───────────┘     │
                            ▼
              ┌─────────────────────────┐
              │ Is desired state met?   │
              │ (creates file exists OR │
              │  refresh_only is true)  │
              └─────────────┬───────────┘
                        Yes │         No
                            ▼         │
                    ┌───────────┐     │
                    │ Skip      │     │
                    └───────────┘     │
                                      ▼
                        ┌─────────────────────────┐
                        │ Is refresh_only = true? │
                        └─────────────┬───────────┘
                                  Yes │         No
                                      ▼         │
                              ┌───────────┐     │
                              │ Skip      │     │
                              └───────────┘     │
                                                ▼
                                        ┌───────────┐
                                        │ Execute   │
                                        └───────────┘

Idempotency

The exec resource provides idempotency through two mechanisms:

Creates Property

The creates property specifies a file that indicates successful prior execution:

- exec:
    - extract-archive:
        command: tar xzf /tmp/app.tar.gz -C /opt
        creates: /opt/app/bin/app

Behavior:

• If /opt/app/bin/app exists, skip execution
• Useful for one-time setup commands
• Provider checks file existence via Status()

Refresh Only Property

The refresh_only property limits execution to subscribe refreshes:

- exec:
    - reload-nginx:
        command: systemctl reload nginx
        refresh_only: true
        subscribe:
          - file#/etc/nginx/nginx.conf

Behavior:

• Command only runs when subscribed resource changes
• Without a subscribe trigger, command is skipped
• Useful for reload/restart commands

Decision Table

Subscribe Behavior

Exec resources can subscribe to other resources and execute when they change:

- file:
    - /etc/app/config.yaml:
        ensure: present
        content: "..."

- exec:
    - reload-app:
        command: systemctl reload app
        refresh_only: true
        subscribe:
          - file#/etc/app/config.yaml

Subscribe takes precedence over other idempotency checks - if a subscribed resource changed, the command executes regardless of creates file existence.

Exit Code Validation

By default, exit code 0 indicates success. The returns property customizes acceptable codes:

- exec:
    - check-status:
        command: /usr/local/bin/check-health
        returns:
          - 0
          - 1
          - 2

Behavior:

• Command succeeds if exit code is in returns list
• Command fails if exit code is not in returns list
• Used for desired state validation after execution

Noop Mode

In noop mode, the exec type:

1. Queries current state normally (checks creates file)
2. Evaluates subscribe triggers
3. Logs what actions would be taken
4. Sets appropriate NoopMessage:
   • “Would have executed”
   • “Would have executed via subscribe”
5. Reports Changed: true if execution would occur
6. Does not call provider Execute method

Desired State Validation

After execution (in non-noop mode), the type verifies success:

func (t *Type) isDesiredState(properties, status) bool {
    // Creates file check takes precedence
    if properties.Creates != "" && status.CreatesSatisfied {
        return true
    }

    // Refresh-only without execution is stable
    if status.ExitCode == nil && properties.RefreshOnly {
        return true
    }

    // Check exit code against acceptable returns
    returns := []int{0}
    if len(properties.Returns) > 0 {
        returns = properties.Returns
    }

    if status.ExitCode != nil {
        return slices.Contains(returns, *status.ExitCode)
    }

    return false
}

If the exit code is not in the acceptable returns list, an ErrDesiredStateFailed error is returned.

Command vs Name

The command property is optional. If not specified, the name is used as the command:

# These are equivalent:
- exec:
    - /usr/bin/myapp --config /etc/myapp.conf:

- exec:
    - run-myapp:
        command: /usr/bin/myapp --config /etc/myapp.conf

Using a descriptive name with explicit command is recommended for clarity.

Environment and Path

Commands can be configured with custom environment:

- exec:
    - build-app:
        command: make build
        cwd: /opt/app
        environment:
          - CC=gcc
          - CFLAGS=-O2
        path: /usr/local/bin:/usr/bin:/bin

Environment:

• Added to the command’s environment
• Format: KEY=value
• Does not replace existing environment

Path:

• Sets the PATH for executable lookup
• Must be absolute directories
• Colon-separated list

File Type

This document describes the design of the file resource type for managing files and directories.

Overview

The file resource manages files and directories with three aspects:

• Existence: Whether the file/directory exists or is absent
• Content: The contents of a file (from inline content or source file)
• Attributes: Owner, group, and permissions

Provider Interface

File providers must implement the FileProvider interface:

type FileProvider interface {
    model.Provider

    CreateDirectory(ctx context.Context, dir string, owner string, group string, mode string) error
    Store(ctx context.Context, file string, contents []byte, source string, owner string, group string, mode string) error
    Status(ctx context.Context, file string) (*model.FileState, error)
}

Method Responsibilities

Status Response

The Status method returns a FileState containing:

type FileState struct {
    CommonResourceState
    Metadata *FileMetadata
}

type FileMetadata struct {
    Name     string         // File path
    Checksum string         // SHA256 hash of contents (files only)
    Owner    string         // Owner username
    Group    string         // Group name
    Mode     string         // Permissions in octal (e.g., "0644")
    Provider string         // Provider name (e.g., "posix")
    MTime    time.Time      // Modification time
    Size     int64          // File size in bytes
    Extended map[string]any // Provider-specific metadata
}

The Ensure field in CommonResourceState is set to:

• present if a regular file exists
• directory if a directory exists
• absent if the path does not exist

Available Providers

Ensure States

Content Sources

Files can receive content from two mutually exclusive sources:

# Inline content with template
- file:
    - /etc/motd:
        ensure: present
        content: |
          Welcome to {{ lookup('facts.hostname') }}
          Managed by CCM
        owner: root
        group: root
        mode: "0644"

# Copy from source file
- file:
    - /etc/app/config.yaml:
        ensure: present
        source: files/config.yaml
        owner: app
        group: app
        mode: "0640"

When using source, the path is relative to the manifest’s working directory if one is set.

Required Properties

Unlike some resources, file resources require explicit attributes:

This prevents accidental creation of files with default or inherited permissions.

Apply Logic

┌─────────────────────────────────────────┐
│ Get current state via Status()          │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ Is current state desired state?         │
└─────────────────┬───────────────────────┘
              Yes │         No
                  ▼         │
          ┌───────────┐     │
          │ No change │     │
          └───────────┘     │
                            ▼
              ┌─────────────────────────┐
              │ What is desired ensure? │
              └─────────────┬───────────┘
                            │
    ┌───────────────────────┼───────────────────────┐
    │ absent                │ directory             │ present
    ▼                       ▼                       ▼
┌────────────┐      ┌───────────────┐      ┌───────────────┐
│ Remove     │      │ CreateDir     │      │ Store         │
│ (os.Remove)│      │               │      │               │
└────────────┘      └───────────────┘      └───────────────┘

Idempotency

The file resource checks multiple attributes for idempotency:

State Checks (in order)

1. Ensure match: Current type matches desired (present/absent/directory)
2. Content match: SHA256 checksum of contents matches (for ensure: present)
3. Owner match: Current owner matches desired
4. Group match: Current group matches desired
5. Mode match: Current permissions match desired

Decision Table