REFERENCE.md

Reference

Table of Contents

Functions

• pam_tools::calculate_pe_memory: This is a crude memory allocation system that is tuned for the base, minimal test memory instance of 4.5GB. This allows you to spin up Conne
• pam_tools::check_for_file: Raises an error if the given file path does not exist or cannot be read.
• pam_tools::generate_random_password: Generate a random password of the given length using Ruby's SecureRandom library.
• pam_tools::generate_randomized_name: Given a stem and optional character count, return a name with a random extension. Useful for generating randomized temp directories, for exam
• pam_tools::get_kots_app: Return the application name based on kots_slug and entitlement from the given license file.
• pam_tools::get_kots_slug: Return the appSlug from a given license file.

Data types

• Pam_tools::Absolute_path: Pattern ensuring a path begins with a POSIX '/', a Windows 'C:' or '', or a 'puppet:/' module file uri.

Tasks

• delete_k8s_app_resources: Delete the kubernetes resources for a given replicated app. Does not remove the app from the Replicated admin console, which allows for re-in
• delete_k8s_resources: Delete a set of kubernetes resources associated with a given selector expression.
• delete_kots_app: Use kubectl-kots to delete an instance of a Replicated app from the Kots admin-console. Note that this does not delete the application resour
• delete_kotsadm: Delete the Kots admin-console applicaiton from the cluster. Note, if you use this on a Kurl host, you will need to re-run the Kurl installer
• destroy_nginx_ingress: Tear down the Nginx IngressController.
• get_ingress_ip: Returns the ip of the ingress load balancer service.
• get_kots_app_status: Return the state of a given Kots application, or not-installed. Will also return not-installed if kots itself is not installed.
• has_ingress_controller: Checks whether an ingress controller is installed.
• helm_add_repository: Add a helm repository.
• helm_install_chart: Install or upgrade a helm chart.
• kots_download: Downloads the currently installed source of a given Kots application from the admin console to the given directory. This task is a wrapper ro
• kots_install: Install a Replicated application with kubectl-kots for testing. This task takes several shortcuts for configuration and security which are no
• kots_upload: Upload the given source directory on the target host to the Kots admin-console, and optionally deploy it. Assumes a version of the applicatio
• list_container_images: Utility for inspecting all the image references from deployment and statefulset container and initContainers in the given namespace.
• start_nginx_ingress: Starts an Nginx IngressController in the cluster. (https://github.com/kubernetes/ingress-nginx)
• update_image: Patch all deployments and statefulset container images matching the given +image_name+ to the given +image_version+.
• wait_for_app: Wait for a Replicated app to deploy and any statefulsets to be ready.
• wait_for_pods: Wait for all pods in a given set of namespaces (or all namespaces if not given) to become ready.
• wait_for_rollout: Wait for rollout of a set of Deployments and Statefulsets based on a k8s selector.

Plans

• pam_tools::install_chart: Install a helm chart. Optionally adds a helm repository_uri before installing. Optionally waits for rollout of the installed chart based
• pam_tools::install_published: Install a published Replicated application via kubectl-kots. Runs kubectl-kots with the given license and configuration and waits for deploy
• pam_tools::teardown: In successive tiers, teardown the application, it's admin-console metadata, and the Kots admin-console itself, if desired. By default, just

Functions

pam_tools::calculate_pe_memory

Type: Puppet Language

This is a crude memory allocation system that is tuned for the base, minimal test memory instance of 4.5GB.

This allows you to spin up Connect on an 8GB test host with the PE components squeezed down into:

pam_tools::calculate_pe_memory(4.5)
#
# {
#   'console_memory'           => 768,
#   'postgres_console_memory'  => 256,
#   'puppetdb_memory'          => 768,
#   'postgres_puppetdb_memory' => 512,
#   'orchestrator_memory'      => 768,
#   'postgres_orch_memory'     => 256,
#   'boltserver_memory'        => 256,
#   'puppetserver_memory'      => 1024,
# }

Leaving remaining memory for the rest of Connect and system.

Greater memory can be allocated to PE as a whole, but the function simply scales linearly, and consequently, this starts to distort the practical memory allocation, since, for example, the console is unlikely to need much more, whereas postgres might. Still you can bump up PE to 8GB or more quickly this way without providing a custom values.yaml.

pam_tools::calculate_pe_memory(Variant[Float,Integer] $allocated_memory_in_gigabytes)

This is a crude memory allocation system that is tuned for the base, minimal test memory instance of 4.5GB.

This allows you to spin up Connect on an 8GB test host with the PE components squeezed down into:

pam_tools::calculate_pe_memory(4.5)
#
# {
#   'console_memory'           => 768,
#   'postgres_console_memory'  => 256,
#   'puppetdb_memory'          => 768,
#   'postgres_puppetdb_memory' => 512,
#   'orchestrator_memory'      => 768,
#   'postgres_orch_memory'     => 256,
#   'boltserver_memory'        => 256,
#   'puppetserver_memory'      => 1024,
# }

Leaving remaining memory for the rest of Connect and system.

Greater memory can be allocated to PE as a whole, but the function simply scales linearly, and consequently, this starts to distort the practical memory allocation, since, for example, the console is unlikely to need much more, whereas postgres might. Still you can bump up PE to 8GB or more quickly this way without providing a custom values.yaml.

Returns: Any Hash of memory resource limits in megabytes, keyed by service. This is suitable for settings for the Helm chart or Connect application config.

allocated_memory_in_gigabytes

Data type: Variant[Float,Integer]

The number of gigabytes allocated specifically to PE. In Connect, for example, you could set this to half the system memory. But the minimum it will allocate is 4.5GB.

pam_tools::check_for_file

Type: Puppet Language

Raises an error if the given file path does not exist or cannot be read.

pam_tools::check_for_file(String $filetype, Optional[String] $path = undef, Boolean $fail_empty_path = true)

Raises an error if the given file path does not exist or cannot be read.

Returns: Any The +path+ if found, or undef if no path given.

filetype

Data type: String

Type of file to display in error messages.

path

Data type: Optional[String]

To the file.

fail_empty_path

Data type: Boolean

If true, fail if no +path+ parameter is given.

pam_tools::generate_random_password

Type: Ruby 4.x API

Generate a random password of the given length using Ruby's SecureRandom library.

pam_tools::generate_random_password(Integer $length)

Generate a random password of the given length using Ruby's SecureRandom library.

Returns: String The password string.

length

Data type: Integer

The number of characters to generate.

pam_tools::generate_randomized_name

Type: Puppet Language

Given a stem and optional character count, return a name with a random extension. Useful for generating randomized temp directories, for example.

Seeding is not tied to host(s), and should be random for each call.

Examples

$r = pam_tools::generate_randomized_name('test', 12)
notice($r)
# Notice: Scope(Class[main]): test.x5gghIjk32ld

pam_tools::generate_randomized_name(String $stem, Integer $count = 10)

Given a stem and optional character count, return a name with a random extension. Useful for generating randomized temp directories, for example.

Seeding is not tied to host(s), and should be random for each call.

Returns: Any A random string of the form '${stem}.${random_char * ${count}}'

Examples

$r = pam_tools::generate_randomized_name('test', 12)
notice($r)
# Notice: Scope(Class[main]): test.x5gghIjk32ld

stem

Data type: String

The start of the string.

count

Data type: Integer

Number of randomized characters to add as a suffix.

pam_tools::get_kots_app

Type: Puppet Language

Return the application name based on kots_slug and entitlement from the given license file.

pam_tools::get_kots_app(String $license)

Return the application name based on kots_slug and entitlement from the given license file.

Returns: Any The associated application name (which may differ from kots_slug).

Raises:

• PuppetError If appSlug cannot be found in the license.

license

Data type: String

A String of the license file content.

pam_tools::get_kots_slug

Type: Puppet Language

Return the appSlug from a given license file.

pam_tools::get_kots_slug(String $license)

Return the appSlug from a given license file.

Returns: Any The appSlug string from the parsed license spec.

Raises:

• PuppetError If appSlug cannot be found.

license

Data type: String

A String of the license file content.

Data types

Pam_tools::Absolute_path

Pattern ensuring a path begins with a POSIX '/', a Windows 'C:' or '', or a 'puppet:/' module file uri.

Alias of

Pattern[/^(\/.*|\\|[A-Z]:\\|puppet:\/)/]

Tasks

delete_k8s_app_resources

Delete the kubernetes resources for a given replicated app. Does not remove the app from the Replicated admin console, which allows for re-installing from subsequent application uploads.

Supports noop? false

Parameters

kots_namespace

Data type: String

The k8s namespace we're operating in.

kots_slug

Data type: String

The Replicated application slug.

scaledown_timeout

Data type: Integer

Seconds to wait for app to scale down to 0 replica before deletion of all related resources.

delete_k8s_resources

Delete a set of kubernetes resources associated with a given selector expression.

Supports noop? false

Parameters

selector

Data type: String

The selector expression constraint. Only delete resources with labels satisfying this expression.

kots_namespace

Data type: String

The k8s namespace we're operating in.

delete_kots_app

Use kubectl-kots to delete an instance of a Replicated app from the Kots admin-console. Note that this does not delete the application resources from kubernetes.

Supports noop? false

Parameters

kots_slug

Data type: Variant[Array[String],String]

The replicated application slug to delete. Or '*' to delete all listed applications from the admin-console.

kots_namespace

Data type: String

The k8s namespace the application is installed in.

force

Data type: Boolean

Remove the application reference from the console even if it was already deployed.

delete_kotsadm

Delete the Kots admin-console applicaiton from the cluster. Note, if you use this on a Kurl host, you will need to re-run the Kurl installer to set kotsadm back up again as kubectl-kots install will not be sufficient to install a kotsadm configured to work properly in the Kurl cluster..

Supports noop? false

Parameters

kots_namespace

Data type: String

The k8s namespace we're operating in.

scaledown_timeout

Data type: Integer

Seconds to wait for app to scale down to 0 replica before deletion of all related resources.

force

Data type: Boolean

Remove kotsadm even if this looks to be a Kurl cluster.

destroy_nginx_ingress

Tear down the Nginx IngressController.

Supports noop? false

get_ingress_ip

Returns the ip of the ingress load balancer service.

Supports noop? false

Parameters

port

Data type: Integer

Service exposing this port.

timeout

Data type: Integer

Number of retry secs. A LoadBalancer service that has just been started, may take several seconds before it reports an available ip address. A retry of 0 will succesfully return nothing if no ip is found, otherwise a timeout error will be raised.

get_kots_app_status

Return the state of a given Kots application, or not-installed. Will also return not-installed if kots itself is not installed.

Supports noop? false

Parameters

kots_slug

Data type: String

The replicated application slug.

kots_namespace

Data type: String

The k8s namespace the application is installed in.

verbose

Data type: Boolean

Return json output, including the full hash of all Kots applicaiton statuses.

has_ingress_controller

Checks whether an ingress controller is installed.

Supports noop? false

helm_add_repository

Add a helm repository.

Supports noop? false

Parameters

repository_name

Data type: String

Name for the helm repository.

repository_uri

Data type: String

Uri for the helm repository.

helm_install_chart

Install or upgrade a helm chart.

Supports noop? false

Parameters

chart

Data type: String

The chart to install. This could be a reference to a chart in a helm repository, or a path to a chart archive or directory.

version

Data type: Optional[String]

If +chart+ is a reference, this is the version to install. If not set, the latest version is installed.

release

Data type: String

The name of the installed instance of the chart.

values

Data type: Optional[String]

YAML override values for chart settings.

namespace

Data type: String

k8s namespace we're installing into.

kots_download

Downloads the currently installed source of a given Kots application from the admin console to the given directory. This task is a wrapper round kubectl-kots download.

Supports noop? false

Parameters

kots_slug

Data type: String

The replicated application slug.

kots_namespace

Data type: String

The k8s namespace we're operating in.

destination

Data type: Optional[String]

The absolute path to the directory to download the application source to. If not given, will default to '/tmp/${kots_slug}'.

clear_upstream

Data type: Boolean

Whether to delete the yaml manifests from the upstream folder after download. This is useful if we are going to replace it with newer upstream source before uploading back to the admin-console for deployment.

kots_install

Install a Replicated application with kubectl-kots for testing. This task takes several shortcuts for configuration and security which are not suitable for production use. It is not idempotent.

Supports noop? false

Parameters

license_content

Data type: String

YAML contents of the license file for the replicated application to install

password

Data type: String[6]

Password to use for the kots admin-console, for the application, and possibly for any other internal passwords (databases?) in the generated app config.

hostname

Data type: String

The resolvable hostname to use when configuring the application.

kots_namespace

Data type: String

The k8s namespace we're operating in.

kots_wait_duration

Data type: String

Timeout waiting for admin-console.

config_content

Data type: Optional[String]

YAML configuration for an automated install of the replicated application. If not provided, a basic config will be generated by the task.

kots_install_options

Data type: Optional[String]

Additional parameters to pass to kubectl-kots install.

airgap_bundle

Data type: Optional[String]

Path on the target of an airgap bundle to install instead of using online installation.

pam_variant

Data type: String

The initial puppet-application-manager channel that will provide configuration for Kots.

kots_upload

Upload the given source directory on the target host to the Kots admin-console, and optionally deploy it. Assumes a version of the application is already installed. This task is a wrapper around kubectl-kots upload.

Supports noop? false

Parameters

kots_slug

Data type: String

The replicated application slug.

kots_namespace

Data type: String

The k8s namespace we're operating in.

source

Data type: String

The absolute path to the source directory to upload.

deploy

Data type: Boolean

Whether to have the admin-console deploy after uploading.

skip_preflights

Data type: Boolean

Whether to skip preflight checks after uploading.

list_container_images

Utility for inspecting all the image references from deployment and statefulset container and initContainers in the given namespace.

Supports noop? false

Parameters

kots_namespace

Data type: String

The k8s namespace we're operating in.

start_nginx_ingress

Starts an Nginx IngressController in the cluster. (https://github.com/kubernetes/ingress-nginx)

Supports noop? false

Parameters

version

Data type: String

The controller version to install in the cluster.

provider

Data type: Optional[String]

The provider implementation to use.

timeout

Data type: Integer

Number of secs to wait for controller to be ready.

update_image

Patch all deployments and statefulset container images matching the given +image_name+ to the given +image_version+.

Supports noop? false

Parameters

image_name

Data type: String

This can be the short name, or the full name for the image including registry (everything to the left of the ':' version/tag separator).

image_version

Data type: String

The new version to patch the image to.

kots_namespace

Data type: String

The k8s namespace we're operating in.

wait_for_app

Wait for a Replicated app to deploy and any statefulsets to be ready.

Supports noop? false

Parameters

kots_slug

Data type: String

Replicated slug for the application.

app_hostname

Data type: String

Resolvable hostname to reach the application locally.

kots_namespace

Data type: String

The k8s namspace we're operating in.

app_timeout

Data type: Pattern[/[0-9]+s/]

Number of seconds to wait for app to deploy.

sts_timeout

Data type: Pattern[/[0-9]+s/]

Number of seconds to wait for Deployment and StatefulSet rollouts to complete.

http_timeout

Data type: Pattern[/[0-9]+s/]

Number of seconds to wait for app http/s to return 'ok'

wait_for_pods

Wait for all pods in a given set of namespaces (or all namespaces if not given) to become ready.

Supports noop? false

Parameters

namespaces

Data type: Optional[String]

Space separated list of namespaces to check. If not given, all namespaces will be checked.

timeout

Data type: Integer

Number of seconds to wait for each pod to become ready.

wait_for_rollout

Wait for rollout of a set of Deployments and Statefulsets based on a k8s selector.

Supports noop? false

Parameters

selector

Data type: String

A k8s selector to constrain resources.

namespace

Data type: String

The k8s namespace to operate in

timeout

Data type: Pattern[/[0-9]+s/]

Number of seconds to wait for Deployment and StatefulSet rollouts to complete.

Plans

pam_tools::install_chart

Install a helm chart.

Optionally adds a helm repository_uri before installing.

Optionally waits for rollout of the installed chart based on a part_of selector.

Parameters

The following parameters are available in the pam_tools::install_chart plan:

• targets
• chart_name
• release
• repository_uri
• values_yaml
• namespace
• part_of
• timeout

targets

Data type: TargetSpec

Test hosts to deploy to.

chart_name

Data type: String

The chart to install.

release

Data type: String

The name of the installed instance of the chart.

repository_uri

Data type: Optional[String]

If a helm repository uri is given, ensure it is added and updated on targets before attempting to install the chart. Will take the repository name from the chart_name prefix/.

Default value: undef

values_yaml

Data type: Optional[String]

Optional yaml string of chart values to pass to Helm.

Default value: undef

namespace

Data type: String

k8s namespace we're installing into.

Default value: 'default'

part_of

Data type: Optional[String]

If given, plan will wait for rollout of deployments and statefulsets matching 'app.kuberneters.io/part-of=${part_of}' until timeout.

Default value: undef

timeout

Data type: Integer

Number of seconds to wait for the services to all be ready.

Default value: 600

pam_tools::install_published

Install a published Replicated application via kubectl-kots.

Runs kubectl-kots with the given license and configuration and waits for deployment.

The kubectl-kots install installs the Replicated Kots admin-console as a side effect if not already installed into the cluster. Initial configuration for Kots comes from one of the puppet-application-manager channels as determined by the +pam_variant+ parameter. By default Kots is installed with puppet-application-manager/stable.

If a password is given, it is used for the Kots admin-console admin login. If no password is given, one will be randomly generated and output at the end of the plan for reference.

If no application configuration file is given, a very basic configuration file is generated using this template.

In the case of cd4pe/cygnus installs, the same password and a root login of [email protected] are set in the generated configuration. If a custom +config_file+ is provided, it is assumed to be complete, and is used instead.

One of the key configuration parameters in the application configuration is the hostname used in the cert and ingress. If a +config_file+ is provided, hostname should be set there and will take precedence.

Alternately, +hostname+ can be set as a parameter, and will be set in the generated config if no +config_file+ is given.

Generally, when working with test hosts, no +config_file+ is given, and +hostname+ is left unset. In this case, the app hostname parameter is populated based on the target automatically, using either the target's hostname in the case of ssh targets, or by generating a wildcard dns hostname that will be recognized by nip.io based on the app name and a lookup of the cluster's ingress load balancer ip. This will be something like cd4pe.10.20.30.40.nip.io, ensuring a connection on 10.20.30.40.

Because kubectl-kots install is not an idempotent operation, if the plan detects that the application has already been installed, it will skip this step and simply wait for the application to be ready.

Parameters

The following parameters are available in the pam_tools::install_published plan:

• targets
• license_file
• password
• config_file
• airgap_bundle
• hostname
• webhook_hostname
• kots_install_options
• pam_variant
• allocated_memory_in_gigabytes
• allocated_cpu
• wait_for_app
• app_timeout

targets

Data type: TargetSpec

The hosts to operate on.

license_file

Data type: Pam_tools::Absolute_path

Path to the application license file.

password

Data type: Optional[String[6]]

Password to use for both the Kots admin-console and for the application itself (if not present in the config_file). If no password is given, one will be randomly generated.

Default value: undef

config_file

Data type: Optional[Pam_tools::Absolute_path]

Absolute path to application configuration defaults. If not provided, a basic config will be generated by the install task.

Default value: undef

airgap_bundle

Data type: Optional[Pam_tools::Absolute_path]

Installs the application from an airgap bundle. Must be an absolute path.

Default value: undef

hostname

Data type: Optional[String]

The application hostname to set in a generated configuration. Ignored if +config_file+ given. Otherwise generated from target if not set (see above).

Default value: undef

webhook_hostname

Data type: Optional[String]

For applications that present a webhook, hosts the webhook on a separate Ingress at the specified hostname rather than an external port.

Default value: undef

kots_install_options

Data type: Optional[String]

Any additional command line options to pass directly to kubectl-kots install when the kots_install task is run. (--skip-preflights=true, or --skip-rbac-check=true, for example...)

Default value: undef

pam_variant

Data type: String

The initial puppet-application-manager channel that will provide configuration for Kots itself prior to Kots installing the application identified by the +license_content+. This can be important for a GKE cluster, for example, which will require 'minimal-rbac' instead of 'stable' unless the service-account used has permissions to modify clusteroles.

Default value: 'stable'

allocated_memory_in_gigabytes

Data type: Variant[Integer,Float]

The total system memory being made available to the application. This should be in integer or float gigabytes. This is used to tune configuration for the app. It will be ignored if you are supplying your own +config_file+, or for any application other than Connect.

Default value: 16

allocated_cpu

Data type: Variant[Integer,Float]

The total number of cpu available to the application. This should be whole or Float fractional cpu, but not millicpu. Currently the only affect is to tighten comply cpu requests to allow it to stand up with <= 4 cpu.

Default value: 8

wait_for_app

Data type: Boolean

Whether or not to wait for app deployment to complete before returning.

Default value: true

app_timeout

Data type: Integer

If waiting for the app, this is the number of seconds to wait for kots to indicate that the app is ready.

Default value: 600

pam_tools::teardown

In successive tiers, teardown the application, it's admin-console metadata, and the Kots admin-console itself, if desired.

By default, just deletes the given app's resources, allowing for a fresh deployment.

Parameters

The following parameters are available in the pam_tools::teardown plan:

• targets
• kots_slug
• kots_namespace
• scaledown_timeout
• remove_app_from_console
• delete_kotsadm

targets

Data type: TargetSpec

The hosts to operate on.

kots_slug

Data type: String

The slug label of the Replicated application to delete.

kots_namespace

Data type: String

The k8s namespace the application is installed in.

Default value: 'default'

scaledown_timeout

Data type: Integer

The number of seconds to wait for the application to scale down while deleting resources.

Default value: 300

remove_app_from_console

Data type: Boolean

If true, then the application metadata will also be deleted from the admin-console. The next installation via kubectl-kots install will recreate a fresh entry for the application in the console.

Default value: false

delete_kotsadm

Data type: Boolean

If true, then the Kotsadm admin-console will also be deleted from the cluster. It should be reinstalled by the next kubectl-kots install command.

Default value: false