cpln apply
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:
- GitOps
- Scripting
- Testing
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 thegvc
to the session context of the profile and will be refered to as the defaultgvc
when executing any future command including thecpln apply
command.cpln profile update PROFILE_NAME --gvc GVC_NAME
-
Specify a
--gvc
flag to theapply
command. This will pass thegvc
as an option and will override the defaultgvc
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
--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 -
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.