​
Overview

The cpln apply command is used to automate the management of Control Plane resources using JSON or YAML metadata as input.

This automation can be used for:

Using cpln apply is a good way to leverage the CLI in an idempotent manner.

The usage, limitations, and example templates are described below.

​
Using the CLI

Using the CLI, the apply command is called by executing:

cpln apply --file FILE_NAME [OPTIONS]

The FILE_NAME is the path for the file and it can be either a JSON or YAML file containing the resource metadata.

To apply an Identity, a Volume Set or a Workload resource you need to specify a GVC using one of the following methods.

  • Specify a gvc within your cpln profile. This will add the gvc to the session context of the profile and will be refered to as the default gvc when executing any future command including the cpln apply command.

    cpln profile update PROFILE_NAME --gvc GVC_NAME

  • Specify a --gvc flag to the apply command. This will pass the gvc as an option and will override the default gvc that is defined in the profile.

    cpln apply --file FILE_NAME --gvc GVC_NAME

  • Specify a gvc property in the resource definition within the file you intend to apply.

    kind: identity
name: example-identity
description: example-description
tags: {}
gvc: example-gvc
You can specify either a GVC property or use the --gvc flag, but not both.

Click here to view the CLI reference page for the apply command.

​
Apply a K8s File

The CLI has the ability to convert K8s resources into Control Plane resources. By passing the --k8s true option to the apply command, the K8s resources will be converted and applied.

cpln apply --file FILE_NAME --k8s true

The apply command utilizes the logic of the CLI convert command and then applies the resulting output.

​
Apply Standard Input

In case you would like to pass Control Plane resources through stdin (Standard Input), use the following command.

CONTROL_PLANE_RESOURCES | cpln apply --file -
This is useful if you want to pass the stdout of a command to the cpln apply command.

​
Using the Console

The console has the ability to upload a JSON or YAML file or accept a resource definition in JSON or YAML as input. The functionality is the same as using the CLI. To start applying, click the cpln apply button in the upper right corner of the console. A modal will be displayed containing the upload instructions.

The cpln apply modal provides the ability to specify in which org and gvc a resource will be executed. The default is your currently selected org and gvc.

A file or an input containing an Identity, a Volume Set or a Workload resource will be executed in the scope of the specified gvc in the cpln apply modal. In case a gvc is defined within a resource, the resource will be executed in the scope of that gvc.

​
Multiple Resources

The apply command can accept a YAML file containing multiple resources. Each resource must be separated using ---.

If a resource has a reference to another resource (e.g., a workload refers to a GVC), the referenced resource must be defined in the same file ONLY in case it does not already exist at Control Plane.

​
Renaming of Resources

If the name of an exisiting resource is changed, the cpln apply command will create a new resource.

NOTE: Any orphaned resources will need to be manually deleted.

​
Limitations

  • To create an agent, use the console or the CLI agent command to obtain the bootstrap config data. Using the cpln apply command from the CLI or console does not output the config data.
  • Before creating a cloud account, additional configuration is required at the target cloud provider. Refer to the Create Cloud Account guide for instructions.
  • Before creating a domain, the required DNS entries must exist. Refer to the Configure a Domain guide for instructions.

​
Generate Sample Input

Samples of existing resources can be generated using the console or the CLI. These samples can assist when defining resources for your application.

Using the console:

  • After selecting a resource, there will be an Actions pull down button in the upper right corner. Inside it you will find the View and Export options.
  • The View will allow you to see the resource definition as JSON, YAML and Terraform.
  • For the Export option select JSON Slim or YAML Slim to download the file.

Using the CLI:

  • Using the get command for each resource, the -o flag can output the resource as JSON or YAML.
  • For example: The command cpln gvc get GVC_NAME -o yaml-slim --org ORG_NAME will output the GVC_NAME as YAML.

The json-slim and yaml-slim format options will output only the necessary values needed for a subsequent call to the cpln apply command.

​
Use in GitOps

The apply command can be used to manage Control Plane resources as part of a CI/CD pipeline.

Refer to the GitOps CLI documentation for additional information.

​
Example Templates

The examples below can be used as templates when creating your own metadata files.

These files can be download here.

Deploy From Docker-Composecpln convert