Infrastructure

Provisioning and operating infrastructure: services, processes, cron, ports and users. Every parameter with its type, default and description, plus worked examples.

Infra

AWS EC2 instance management with reboot, start/stop, and terminate operations.

Parameters

Parameter	Type	Required	Default	Description
command	string	Yes	—	Operation: reboot, start_stop, terminate
id	string	Yes	—	EC2 instance ID
dryrun	bool	No	false	Perform a dry run (AWS DryRun flag)

The task also requires an environment configuration with AWS credentials and region settings.

Actions

Command	Description
reboot	Reboot an EC2 instance
start_stop	Start or stop an EC2 instance
terminate	Terminate an EC2 instance

Examples

Reboot an instance

tasks:
  - name: reboot-instance
    infra:
      command: reboot
      id: "i-0123456789abcdef0"

Terminate an instance

tasks:
  - name: terminate-instance
    infra:
      command: terminate
      id: "i-0123456789abcdef0"

Dry run

tasks:
  - name: test-reboot
    infra:
      command: reboot
      id: "i-0123456789abcdef0"
      dryrun: true

Service

OS service management with list, status, start, stop, restart, enable, disable, and create operations. Cross-platform support for systemd (Linux), launchd (macOS), and sc.exe (Windows).

Parameters

Parameter	Type	Required	Default	Description
action	string	Yes	—	Operation to perform (see Actions)
name	string	Yes*	—	Service name
filter	string	No	—	Substring filter for list action
description	string	No	—	Human-readable description (create)
command	string	Yes**	—	Executable path (create)
args	[]map	No	—	Command arguments (create)
workdir	string	No	—	Working directory (create)
user	string	No	—	OS user to run service as (create)
start_type	string	No	auto	Start type: auto, manual, disabled (create)
environment	[]map	No	—	Environment variables as key/value pairs (create)
restart_policy	string	No	on-failure	Restart policy: always, on-failure, no (create)
restart_sec	int	No	5	Seconds before restart (create)
after	[]map	No	—	Service dependencies (create)
enable_on_create	bool	No	true	Enable service after creation
start_on_create	bool	No	true	Start service after creation

* Required for all actions except list. ** Required for create.

Actions

Action	Description
list	List all services (optionally filtered)
status	Check service status
start	Start a service
stop	Stop a service
restart	Restart a service
enable	Enable a service for automatic startup
disable	Disable a service from automatic startup
create	Create a new service unit

Examples

List all services

tasks:
  - name: list-services
    service:
      action: list

List services filtered by name

tasks:
  - name: find-nginx
    service:
      action: list
      filter: nginx

Check service status

tasks:
  - name: check-nginx
    service:
      action: status
      name: nginx

Start a service

tasks:
  - name: start-nginx
    service:
      action: start
      name: nginx

Stop a service

tasks:
  - name: stop-nginx
    service:
      action: stop
      name: nginx

Restart a service

tasks:
  - name: restart-nginx
    service:
      action: restart
      name: nginx

Enable and disable a service

tasks:
  - name: enable-nginx
    service:
      action: enable
      name: nginx

  - name: disable-nginx
    service:
      action: disable
      name: nginx

Create a simple service

tasks:
  - name: create-myapp
    service:
      action: create
      name: myapp
      description: "My Application Service"
      command: /usr/local/bin/myapp
      args:
        - value: "--port"
        - value: "8080"

Create a service with full options

tasks:
  - name: create-webapp
    service:
      action: create
      name: webapp
      description: "Web Application Server"
      command: /opt/webapp/bin/server
      args:
        - value: "--config"
        - value: "/etc/webapp/config.yaml"
      workdir: /opt/webapp
      user: www-data
      start_type: auto
      restart_policy: always
      restart_sec: 10
      environment:
        - key: NODE_ENV
          value: production
        - key: PORT
          value: "3000"
      after:
        - value: network.target
        - value: postgresql.service

Create without auto-start

tasks:
  - name: create-worker
    service:
      action: create
      name: worker
      description: "Background Worker"
      command: /opt/worker/bin/worker
      start_type: manual
      enable_on_create: true
      start_on_create: false

Template-driven service management

vars:
  service_name: nginx
tasks:
  - name: check-service
    service:
      action: status
      name: "{{service_name}}"

  - name: restart-service
    service:
      action: restart
      name: "{{service_name}}"

Create service with template variables

vars:
  app_name: myapi
  app_binary: /opt/myapi/bin/server
  app_port: "9090"
  app_dir: /opt/myapi
tasks:
  - name: create-api-service
    service:
      action: create
      name: "{{app_name}}"
      description: "API Service for {{app_name}}"
      command: "{{app_binary}}"
      args:
        - value: "--port"
        - value: "{{app_port}}"
      workdir: "{{app_dir}}"
      user: www-data
      restart_policy: on-failure
      restart_sec: 5

Process

OS process management with list, check, kill, find, and start operations. Cross-platform support.

Parameters

Parameter	Type	Required	Default	Description
action	string	Yes	—	Operation: list, check, kill, find, start
name	string	No	—	Process name or pattern
pid	int	No	—	Process ID
signal	string	No	KILL	Signal to send (kill)
command	string	No	—	Command to run (start)
args	[]map	No	—	Command arguments (start)
workdir	string	No	—	Working directory (start)
background	bool	No	false	Run in background (start)

All string parameters support Liquid template variables.

Actions

Action	Description
list	List running processes (optionally filtered by name)
check	Check if a process is running (by name or PID)
kill	Kill a process (by name or PID, with signal)
find	Find processes matching a name pattern
start	Start a new process (foreground or background)

Examples

List all running processes

tasks:
  - name: list-processes
    process:
      action: list

List processes filtered by name

tasks:
  - name: find-nginx
    process:
      action: list
      name: nginx

Check if a process is running by name

tasks:
  - name: check-nginx
    process:
      action: check
      name: nginx

Check if a process is running by PID

tasks:
  - name: check-pid
    process:
      action: check
      pid: 1234

Kill a process by name

tasks:
  - name: kill-nginx
    process:
      action: kill
      name: nginx

Kill a process with a specific signal

tasks:
  - name: graceful-stop
    process:
      action: kill
      pid: 1234
      signal: TERM

Find processes matching a pattern

tasks:
  - name: find-matching
    process:
      action: find
      name: nginx

Start a foreground command

tasks:
  - name: run-migration
    process:
      action: start
      command: /usr/bin/python3
      args:
        - value: manage.py
        - value: migrate
      workdir: /opt/app

Start a background daemon

tasks:
  - name: start-server
    process:
      action: start
      command: /usr/local/bin/myserver
      args:
        - value: "--port"
        - value: "8080"
      background: true

Template-driven process management

vars:
  service_name: nginx
  kill_signal: TERM
tasks:
  - name: check-service
    process:
      action: check
      name: "{{service_name}}"

  - name: stop-service
    process:
      action: kill
      name: "{{service_name}}"
      signal: "{{kill_signal}}"

  - name: verify-stopped
    process:
      action: check
      name: "{{service_name}}"

Start command with template variables

vars:
  app_cmd: /opt/app/server
  app_port: "3000"
  app_dir: /opt/app
tasks:
  - name: start-app
    process:
      action: start
      command: "{{app_cmd}}"
      args:
        - value: "--port"
        - value: "{{app_port}}"
      workdir: "{{app_dir}}"
      background: true

Cron

Scheduled job management with support for recurring and one-time jobs, execution, logging, and OS scheduler sync.

Parameters

Parameter	Type	Required	Default	Description
action	string	Yes	—	Operation to perform (see Actions)
name	string	Yes*	—	Job name
command	string	Yes**	—	Command to execute
schedule	string	Yes***	—	Schedule expression (human-friendly or cron)
time	string	Yes****	—	Time for one-time jobs (now, in 5 minutes, today at 3pm)
dir	string	No	—	Working directory for job execution
shell	string	No	/bin/sh	Shell to use
env	[]map	No	—	Environment variables (key/value pairs)
timeout	string	No	—	Job timeout as duration (30m, 1h)
overlap	string	No	—	Concurrent execution: skip, queue, allow
enabled	bool	No	true	Whether job is active
lines	int	No	50	Number of lines for logs/history
direction	string	No	both	Sync direction: to-os, from-os, both
dry_run	bool	No	false	Preview sync changes without applying

* Required for all actions except list and sync. ** Required for add and once. *** Required for add. **** Required for once.

Actions

Action	Description
add	Add a recurring scheduled job
once	Schedule a one-time job
remove	Remove a job
list	List all managed jobs
show	Show details of a specific job
exec	Execute a job immediately (foreground)
run	Run a job in the background
logs	View job log output
history	View job execution history
sync	Sync between YAML store and OS scheduler

Schedule Expressions

The schedule parameter accepts both human-friendly expressions and raw cron syntax:

Format	Example
Human-friendly	daily at 2am, weekly on monday at 9am, every 5 minutes
Raw cron	cron */5 * * * *, cron 0 2 * * *

Examples

Add a daily job

tasks:
  - name: add-backup
    cron:
      action: add
      name: daily-backup
      command: /opt/scripts/backup.sh
      schedule: daily at 2am
      dir: /opt/backup
      timeout: 1h
      env:
        - key: BACKUP_DIR
          value: /mnt/backups
      enabled: true

Add a job with raw cron expression

tasks:
  - name: add-health-check
    cron:
      action: add
      name: health-check
      command: curl -sf http://localhost:8080/health
      schedule: cron */5 * * * *
      timeout: 30s

Schedule a one-time job

tasks:
  - name: run-deployment
    cron:
      action: once
      name: deploy-v2
      command: /opt/scripts/deploy.sh --version v2.0.0
      time: today at 11pm
      dir: /opt/app

Execute immediately

tasks:
  - name: run-now
    cron:
      action: once
      name: db-migrate
      command: /opt/scripts/migrate.sh
      time: now

List all jobs

tasks:
  - name: list-jobs
    cron:
      action: list

Show job details

tasks:
  - name: show-details
    cron:
      action: show
      name: daily-backup

Execute a job in foreground

tasks:
  - name: run-foreground
    cron:
      action: exec
      name: daily-backup

Run a job in background

tasks:
  - name: run-background
    cron:
      action: run
      name: daily-backup

View job logs

tasks:
  - name: view-logs
    cron:
      action: logs
      name: daily-backup
      lines: 100

View execution history

tasks:
  - name: view-history
    cron:
      action: history
      name: daily-backup
      lines: 20

Remove a job

tasks:
  - name: remove-job
    cron:
      action: remove
      name: health-check

Sync to OS scheduler

tasks:
  - name: sync-jobs
    cron:
      action: sync
      direction: to-os

Dry-run sync

tasks:
  - name: preview-sync
    cron:
      action: sync
      direction: both
      dry_run: true

Using template variables

vars:
  env_name: production
  report_email: [email protected]
tasks:
  - name: add-weekly-report
    cron:
      action: add
      name: "weekly-report-{{ env_name }}"
      command: "/opt/scripts/report.sh --env {{ env_name }}"
      schedule: weekly on monday at 9am
      env:
        - key: REPORT_EMAIL
          value: "{{ report_email }}"

Namespace: cron

Scheduled job management functions.

Scope: System

Functions

Function	Description
cron.add()	Add a recurring scheduled job
cron.once()	Schedule a one-time job
cron.remove()	Remove a job
cron.list()	List all managed jobs
cron.show()	Show job details
cron.exec()	Execute a job in foreground
cron.run()	Run a job in background
cron.logs()	View job log output
cron.history()	View job execution history
cron.sync()	Sync with OS scheduler

See the cron namespace documentation for detailed per-function parameters, returns, and examples.

Port

Unified TCP/UDP port management with check, find, list, and kill operations.

Parameters

Parameter	Type	Required	Default	Description
action	string	Yes	—	Operation: check, find, list, kill
port	string	Yes*	—	Target port number
startport	string	No	3000	Range start (find)
endport	string	No	65000	Range end (find)
increment	string	No	1000	Step size (find)
minport	string	No	10000	Skip ports below this value (find)
protocol	string	No	tcp	Protocol: tcp or udp
signal	string	No	KILL	Signal to send (kill)
set	string	No	baseport	Output variable name for found port (find)

*Port is required for check, list, and kill. All string values support Liquid templates.

Actions

Action	Description
check	Check if a port is free
find	Find the first free port in a range
list	List processes using a port
kill	Kill all processes on a port

Examples

Check if a port is free

tasks:
  - name: verify-port
    port:
      action: check
      port: "8080"

Find a free base port

Scans from startport to endport in steps of increment, skipping ports below minport. The found port is stored in the variable specified by set.

tasks:
  - name: find-port
    port:
      action: find
      startport: "10000"
      endport: "60000"
      increment: "1000"
      set: baseport

List processes on a port

tasks:
  - name: show-processes
    port:
      action: list
      port: "8080"

Kill processes on a port

tasks:
  - name: free-port
    port:
      action: kill
      port: "8080"
      signal: TERM

Using template variables

vars:
  target_port: "8080"
tasks:
  - name: check-port
    port:
      action: check
      port: "{{target_port}}"

Namespace: port

TCP/UDP port management functions.

Scope: System

Functions

Function	Description
port.check()	Check if a port is free
port.find()	Find the first free port in a range
port.list()	List processes using a port
port.kill()	Kill all processes on a port

port.check()

Check if a TCP/UDP port is free.

Input: int (port number) or map with keys: port, protocol

Returns:

Field	Type	Description
success	bool	Whether the check succeeded
free	bool	Whether the port is free
error	string	Error message if failed

// Simple check with port number
let result = port.check(8080)
if (result.free) {
  log("Port 8080 is available")
}

// Check with protocol
let result = port.check({ port: 3000, protocol: "udp" })
log("Free: " + result.free)

port.find()

Find the first free port in a range.

Input: map with keys: startport, endport, increment, minport, protocol

Returns:

Field	Type	Description
success	bool	Whether a free port was found
port	int	The free port number
error	string	Error message if failed

// Find free port in range
let result = port.find({
  startport: 10000,
  endport: 60000,
  increment: 100
})
log("Free port: " + result.port)

// Find with minimum port
let result = port.find({
  startport: 3000,
  endport: 65000,
  increment: 1000,
  minport: 10000
})

port.list()

List processes using a port.

Input: int (port number) or map with keys: port, protocol

Returns:

Field	Type	Description
success	bool	Whether the listing succeeded
processes	array	Array of process objects with pid, user, command
error	string	Error message if failed

// List processes on a port
let result = port.list(8080)
for (let p of result.processes) {
  log(p.pid + " " + p.user + " " + p.command)
}

port.kill()

Kill all processes on a port.

Input: int (port number) or map with keys: port, protocol, signal

Returns:

Field	Type	Description
success	bool	Whether the kill succeeded
free	bool	Whether the port is now free
error	string	Error message if failed

// Kill with default signal (KILL)
port.kill(8080)

// Graceful termination
port.kill({ port: 8080, signal: "TERM" })

// Kill UDP port processes
port.kill({ port: 5353, protocol: "udp", signal: "TERM" })

User

OS user management with check, create, delete, modify, and password operations.

Parameters

Parameter	Type	Required	Default	Description
action	string	Yes	—	Operation: check, create, delete, modify, passwd
username	string	Yes	—	Target OS username
groupname	string	No	—	Primary group name
shell	string	No	/bin/bash	Login shell path
home	string	No	—	Home directory path
groups	[]string	No	—	Supplementary groups
password	string	No	—	User password (plain text)
createhome	bool	No	true	Create home directory
removehome	bool	No	false	Remove home directory on deletion
system	bool	No	false	Create as system account

All string parameters support Liquid template variables.

Actions

Action	Description
check	Check if a user exists (returns uid, gid, homedir)
create	Create a new OS user
delete	Delete an OS user
modify	Modify user properties
passwd	Set or change a user password

Examples

Check if user exists

tasks:
  - name: verify-user
    user:
      action: check
      username: "{{target_user}}"

Create user with group

tasks:
  - name: create-app-user
    user:
      action: create
      username: appuser
      groupname: appgroup
      groups:
        - docker
        - sudo

Create a system account

tasks:
  - name: create-system-user
    user:
      action: create
      username: myservice
      system: true
      createhome: false
      shell: /usr/sbin/nologin

Delete user

tasks:
  - name: remove-user
    user:
      action: delete
      username: olduser
      removehome: true

Modify user groups

tasks:
  - name: update-groups
    user:
      action: modify
      username: appuser
      groups:
        - docker
        - sudo
        - adm

Set password

tasks:
  - name: set-password
    user:
      action: passwd
      username: "{{target_user}}"
      password: "{{user_password}}"

Namespace: user

OS user management functions.

Scope: System

Functions

Function	Description
user.check()	Check if a user exists
user.create()	Create a new user
user.delete()	Delete a user
user.modify()	Modify user properties
user.passwd()	Set or change a user password

user.check()

Check if an OS user exists.

Input: string (username) or map with key: username

Returns:

Field	Type	Description
success	bool	Whether the check succeeded
exists	bool	Whether the user exists
uid	string	User’s numeric UID
gid	string	User’s numeric GID
homedir	string	User’s home directory
error	string	Error message if failed

// Simple check with username string
let result = user.check("deploybot")
if (result.exists) {
  log("UID: " + result.uid)
  log("Home: " + result.homedir)
}

user.create()

Create a new OS user.

Input: string (username) or map with keys: username, groupname, shell, home, groups, createhome, system

Returns:

Field	Type	Description
success	bool	Whether the user was created
error	string	Error message if failed

// Simple create
user.create("deploybot")

// Create with options
user.create({
  username: "deploybot",
  groupname: "deploy",
  groups: ["docker", "sudo"],
  shell: "/bin/bash"
})

// Create system account
user.create({
  username: "myservice",
  system: true,
  createhome: false
})

user.delete()

Delete an OS user.

Input: string (username) or map with keys: username, removehome

Returns:

Field	Type	Description
success	bool	Whether the user was deleted
error	string	Error message if failed

// Simple delete
user.delete("olduser")

// Delete with home directory removal
user.delete({ username: "olduser", removehome: true })

user.modify()

Modify OS user properties.

Input: map with keys: username, groupname, shell, home, groups

Returns:

Field	Type	Description
success	bool	Whether the modification succeeded
error	string	Error message if failed

user.modify({
  username: "deploybot",
  groups: ["docker", "sudo", "adm"],
  shell: "/bin/zsh"
})

user.passwd()

Set or change a user password.

Input: map with keys: username, password

Returns:

Field	Type	Description
success	bool	Whether the password was set
error	string	Error message if failed

user.passwd({
  username: "deploybot",
  password: "new-password-123"
})

Full workflow example

// Check if user exists, create if not
let result = user.check("deploybot")
if (!result.exists) {
  user.create({
    username: "deploybot",
    groupname: "deploy",
    groups: ["docker", "sudo"],
    shell: "/bin/bash"
  })

  user.passwd({
    username: "deploybot",
    password: "initial123"
  })
}

// Modify existing user
user.modify({
  username: "deploybot",
  groups: ["docker", "sudo", "adm"]
})

Deploy Product

Reads an application manifest and assigns static ports for product deployment. Computes port assignments starting at baseport + 251, incrementing by 100 for each application.

Parameters

Parameter	Type	Required	Default	Description
customername	string	Yes	—	Customer name
productname	string	Yes	—	Product name
environmentname	string	Yes	—	Environment name

Prerequisites

• An apps.yaml file must exist at the environment’s product path
• A baseport variable must be set in the environment context (integer)

The task reads from:

/home/environmentuser/environments/{customer}/{environment}/products/{product}/apps/apps.yaml

Output

Sets appdomains in the workflow context with the selected applications and their assigned static ports.

Examples

Deploy a product

tasks:
  - name: deploy-product
    deployproduct:
      customername: acme
      productname: webapp
      environmentname: production

With template variables

vars:
  customer: "{{customer_name}}"
  product: "{{product_name}}"
  env: "{{environment_name}}"
tasks:
  - name: deploy-product
    deployproduct:
      customername: "{{customer}}"
      productname: "{{product}}"
      environmentname: "{{env}}"

Scaffold

Template application, SQL DDL conversion, and error code extraction utilities.

Parameters

Parameters vary by action.

Common

Parameter	Type	Required	Default	Description
action	string	Yes	—	Operation: apply-template, sql-to-yaml, error-json

apply-template

Parameter	Type	Required	Default	Description
templatetype	string	Yes	—	Template type: app, template, plugin
templateslug	string	Yes	—	Template slug with optional version ([email protected])
url	string	Yes	—	Brahma artifact service URL
destination	string	Yes	—	Output directory
name	string	No	—	Override default folder name
checkIfExists	string	No	—	Verify template exists before download

sql-to-yaml

Parameter	Type	Required	Default	Description
inputpath	string	Yes	—	Path to SQL DDL file
outputpath	string	Yes	—	Output directory or file path
dbtype	string	Yes	—	Database type (postgres, mysql)
yamlname	string	No	—	Output YAML file name
referencename	string	No	—	Name for references output file
yamlperentity	bool	No	false	Create one file per entity
fileprefix	string	No	—	Prefix for per-entity files

error-json

Parameter	Type	Required	Default	Description
service	string	Yes	—	Service name prefix for error codes
path	string	Yes	—	Path to Go source file containing error definitions
output	string	Yes	—	Path for generated JSON output

Actions

Action	Description
apply-template	Download and apply a Brahma template
sql-to-yaml	Convert SQL DDL to YAML entity definitions
error-json	Extract error codes from Go source to JSON

Examples

Apply a template

tasks:
  - name: apply-template
    scaffold:
      action: apply-template
      templatetype: app
      templateslug: "[email protected]"
      url: "https://brahma.example.com"
      destination: "/opt/output"
      name: "my-project"

Apply template with existence check

vars:
  project_name: my-service
  app_slug: "my-template@latest"
tasks:
  - name: apply-template
    scaffold:
      action: apply-template
      templatetype: template
      templateslug: "{{app_slug}}"
      url: "https://brahma.example.com"
      destination: "/opt/output"
      name: "{{project_name}}"
      checkIfExists: "true"

Apply a plugin template

tasks:
  - name: apply-plugin
    scaffold:
      action: apply-template
      templatetype: plugin
      templateslug: "[email protected]"
      url: "https://brahma.example.com"
      destination: "/opt/plugins"

Convert SQL DDL to single YAML

tasks:
  - name: convert-sql
    scaffold:
      action: sql-to-yaml
      inputpath: "/data/schema.sql"
      outputpath: "/data/output/schema.yaml"
      dbtype: postgres

Convert SQL with entity/reference splitting

tasks:
  - name: convert-with-refs
    scaffold:
      action: sql-to-yaml
      inputpath: "/data/schema.sql"
      outputpath: "/data/output"
      dbtype: mysql
      yamlname: entities
      referencename: references

Convert SQL to per-entity files

tasks:
  - name: per-entity
    scaffold:
      action: sql-to-yaml
      inputpath: "/data/schema.sql"
      outputpath: "/data/output"
      dbtype: postgres
      yamlperentity: true
      fileprefix: "ds"
      referencename: "references"

Template-driven SQL conversion

vars:
  sql_file: /data/tables.sql
  output_dir: /data/yaml
  db: postgres
tasks:
  - name: convert
    scaffold:
      action: sql-to-yaml
      inputpath: "{{sql_file}}"
      outputpath: "{{output_dir}}"
      dbtype: "{{db}}"
      yamlperentity: true

Generate error JSON from Go source

tasks:
  - name: generate-errors
    scaffold:
      action: error-json
      service: "myservice-"
      path: "/opt/myservice/errors/errors.go"
      output: "/opt/myservice/errors.json"

Error JSON with template variables

vars:
  svc_name: "myservice-"
  errors_file: /opt/myservice/errors/errors.go
  output_file: /opt/myservice/errors.json
tasks:
  - name: generate-errors
    scaffold:
      action: error-json
      service: "{{svc_name}}"
      path: "{{errors_file}}"
      output: "{{output_file}}"

Kong

Kong API Gateway declarative YAML configuration management with service, certificate, and route operations. Also supports certificate expiry checking and ACME renewal.

Parameters

Parameter	Type	Required	Default	Description
action	string	Yes	—	Operation to perform (see Actions)
path	string	Yes	—	Path to Kong YAML configuration file
key	string	No	—	Target name (service name, SNI name)
value	string	No	—	YAML content or hostname
parsebefore	bool	No	false	Render Liquid templates before YAML parsing
commands	[]map	No	—	Array of batch operations (multi-command mode)
expiryduration	string	No	168h	Certificate expiry look-ahead window
updateemail	string	No	[email protected]	ACME registration email
dnsprovider	string	No	godaddy	DNS provider for ACME challenges
force	bool	No	false	Force certificate renewal even if not expired

Command Object (for commands array)

Field	Type	Description
type	string	Command type (same as action values)
key	string	Target name
value	string	YAML content or hostname

Actions

Action	Description
add-service	Add a service to Kong configuration
update-service	Update an existing service by name
remove-service	Remove a service by name
add-cert	Add a TLS certificate
update-cert	Update an existing certificate by SNI name
remove-cert	Remove a certificate by SNI name
add-service-route	Add a hostname to a service route
remove-service-route	Remove a hostname from a service route
check-certs	Check certificate expiry status
renew-certs	Renew expired certificates via ACME

Examples

Add a service

tasks:
  - name: add-service
    kong:
      action: add-service
      path: /opt/kong/kong.yml
      value: |
        name: "{{env}}-{{username}}-api"
        url: "https://localhost:{{baseport}}"
        tags:
          - https
          - "{{env}}-{{username}}"
        connect_timeout: 500000
        read_timeout: 500000
        write_timeout: 500000
        routes:
          - name: "{{env}}-{{username}}-route"
            paths:
              - /
            protocols:
              - http
              - https
            strip_path: false

Update a service

tasks:
  - name: update-service
    kong:
      action: update-service
      path: /opt/kong/kong.yml
      key: "production-myapp-api"
      value: |
        name: "production-myapp-api"
        url: "https://localhost:9090"
        read_timeout: 600000

Remove a service

tasks:
  - name: remove-service
    kong:
      action: remove-service
      path: /opt/kong/kong.yml
      key: "old-service"

Add a TLS certificate

tasks:
  - name: add-cert
    kong:
      action: add-cert
      path: /opt/kong/kong.yml
      parsebefore: true
      value: |
        cert: "{{domainscert}}"
        key: "{{domainskey}}"
        snis:
          - name: "*.{{envslug}}.{{envdomain}}"

Update a certificate

tasks:
  - name: update-cert
    kong:
      action: update-cert
      path: /opt/kong/kong.yml
      key: "*.example.com"
      value: |
        cert: "{{new_cert}}"
        key: "{{new_key}}"

Remove a certificate

tasks:
  - name: remove-cert
    kong:
      action: remove-cert
      path: /opt/kong/kong.yml
      key: "*.old-domain.com"

Add a hostname to a service route

tasks:
  - name: add-route-host
    kong:
      action: add-service-route
      path: /opt/kong/kong.yml
      key: "my-service"
      value: "newhost.example.com"

Remove a hostname from a service route

tasks:
  - name: remove-route-host
    kong:
      action: remove-service-route
      path: /opt/kong/kong.yml
      key: "my-service"
      value: "oldhost.example.com"

Multi-command batch editing

Multiple operations can be performed in a single task using the commands array:

tasks:
  - name: batch-edit
    kong:
      action: add-service
      path: /opt/kong/kong.yml
      parsebefore: true
      commands:
        - type: add-service
          value: |
            name: "new-service"
            url: "http://localhost:9090"
            routes:
              - name: "new-route"
                hosts:
                  - "new.example.com"
        - type: remove-service
          key: "old-service"
        - type: add-service-route
          key: "existing-service"
          value: "extra-host.example.com"

Check certificate expiry

tasks:
  - name: check-certs
    kong:
      action: check-certs
      path: /opt/kong/kong.yml
      expiryduration: "168h"

Renew expired certificates

tasks:
  - name: renew-certs
    kong:
      action: renew-certs
      path: /opt/kong/kong.yml
      updateemail: "[email protected]"
      dnsprovider: "godaddy"
      force: false

Force-renew all certificates

tasks:
  - name: force-renew
    kong:
      action: renew-certs
      path: /opt/kong/kong.yml
      updateemail: "[email protected]"
      dnsprovider: "cloudflare"
      force: true
      expiryduration: "720h"

CoreDNS

CoreDNS zone file management with add and remove record operations. Automatically increments the zone serial number on changes.

Parameters

Parameter	Type	Required	Default	Description
commands	[]map	Yes	—	Array of DNS record operations

Command Object

Field	Type	Required	Description
path	string	Yes	Path to the CoreDNS zone file
type	string	Yes	Operation: add-record or remove-record
value	string	Yes	DNS record as space-separated name ttl type value

Actions

Action	Description
add-record	Add a DNS record to a zone file
remove-record	Remove a DNS record from a zone file

Examples

Add a DNS record

tasks:
  - name: add-dns-record
    coredns:
      commands:
        - path: /etc/coredns/zones/example.com.db
          type: add-record
          value: "app 3600 A 10.0.1.50"

Remove a DNS record

tasks:
  - name: remove-dns-record
    coredns:
      commands:
        - path: /etc/coredns/zones/example.com.db
          type: remove-record
          value: "old-app 3600 A 10.0.1.50"

Multiple record operations

tasks:
  - name: update-dns
    coredns:
      commands:
        - path: /etc/coredns/zones/example.com.db
          type: add-record
          value: "web 3600 A 10.0.1.100"
        - path: /etc/coredns/zones/example.com.db
          type: add-record
          value: "api 3600 A 10.0.1.101"
        - path: /etc/coredns/zones/example.com.db
          type: remove-record
          value: "legacy 3600 A 10.0.1.10"

Using template variables

vars:
  zone_file: /etc/coredns/zones/example.com.db
  app_ip: "10.0.1.50"
tasks:
  - name: add-app-record
    coredns:
      commands:
        - path: "{{zone_file}}"
          type: add-record
          value: "app 3600 A {{app_ip}}"

Credential Provider

Retrieves credentials from a credential provider for use in workflows. Supports Git, SSH, and Database credential types.

Parameters

Parameter	Type	Required	Default	Description
credentialname	string	Yes	—	Name of the credential to retrieve
credentialtype	string	Yes	—	Credential type: git, ssh, database
setkey	string	No	—	Variable key to store the credential in workflow context

Credential Types

Type	Description
git	Git repository credentials (URL-based)
ssh	SSH connection credentials (host-based)
database	Database connection credentials (host-based)

Output

When setkey is provided, the retrieved credential is stored as a JSON-marshaled value in the workflow context under the specified key for use by downstream tasks.

Examples

Retrieve Git credentials

tasks:
  - name: get-git-creds
    credential-provider:
      credentialname: github-deploy
      credentialtype: git
      setkey: git_credentials

Retrieve SSH credentials

tasks:
  - name: get-ssh-creds
    credential-provider:
      credentialname: production-server
      credentialtype: ssh
      setkey: ssh_credentials

Retrieve database credentials

tasks:
  - name: get-db-creds
    credential-provider:
      credentialname: postgres-main
      credentialtype: database
      setkey: db_credentials