The Paco CLI¶
The paco
CLI is used to create, update and delete your cloud resources.
The CLI is divided into sub-commands. Run paco --help
to see them:
$ paco --help
Usage: paco [OPTIONS] COMMAND [ARGS]...
Paco: Prescribed Automation for Cloud Orchestration
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
delete Delete cloud resources
init Create a new Paco project.
provision Create and configure cloud resources.
validate Validate cloud resources.
For most commands, you will need to tell paco
where your Paco config directory is located.
You can do this with the --home
argument, or you can set an PACO_HOME
environment variable.
Init¶
The paco init
is divided into sub-commands:
paco init project <project-name>
: Creates a new directory with a boilerplate Paco project in it.paco init credentials
: Initializes the .credentials file for a Paco project.paco init accounts
: Initializes the accounts for a Paco project.
Cloud commands¶
There are three cloud commands to interact with the cloud:
paco validate <CONFIG_SCOPE>
: Generates CloudFormation and validates it with AWS.paco provision <CONFIG_SCOPE>
: Creates or updates cloud resources.paco delete <CONFIG_SCOPE>
: Deletes cloud resources.
The CONFIG_SCOPE argument is a reference to an object in the Paco project configuration.
Paco CLI config file¶
A .pacoconfig
file can be used to set default Paco CLI options.
This file supports the --warn
and --verbose
options:
warn: true
verbose: true
Config Scope¶
A CONFIG_SCOPE is a valid Paco reference to a Paco object. Paco references start at the top of the Paco project tree and walk their way down. Consider the following Paco project:
paco-project/
accounts/
master.yaml
prod.yaml
dev.yaml
monitor/
Logging.yaml
AlarmSets.yaml
project.yaml
netenv/
saas.yaml
intra.yaml
resource/
CloudTrail.yaml
CodeCommit.yaml
EC2.yaml
IAM.yaml
SNSTopics.yaml
Route53.yaml
S3.yaml
service/
CustomAddOn.yaml
The top-level directory named paco-project
is the start of the scope and project configuration
is contained in the project.yaml
file. You can not express this root scope with CONFIG_SCOPE.
CONFIG_SCOPE will start by expressing a directory in the Paco project. This can be one of four directories: accounts, netenv, resource or service. We will look at how scope works in each directory.
Note
Case insensitive filenames
The YAML filenames are case-insensitive. The scope resource.cloudTRAIL
will match
the filename resource/CloudTrail.yaml
.
accounts scope¶
The accounts directory only has a single scope: accounts
.
This will apply account actions on all accounts listed in the organization_account_ids:
field
in the accounts/master.yaml
file. Typically you will create new accounts by giving them names
in the organization_account_ids:
list and then running paco provision accounts
to create them.
There are no validate or delete commands for the accounts scope. If you need to delete an account, you should
follow the AWS steps to close an account and then delete the appropriate accounts/<account-name>.yaml
file.
netenv scope¶
The netenv scope is used to select environments, regions and applications for a single NetworkEnvironment.
At a minimum, you must specify a NetworkEnvironment and Environment with this scope:
netenv.saas.dev
The NetworkEnvironment is the name of a YAML file in the netenv directory, e.g. netenv/saas.yaml
.
The Environment is the name of an environment in the environment:
section of a netenv file.
For example, consider this netenv file:
network:
title: "My SaaS network"
enabled: true
availability_zones: 2
...
applications:
saas:
title: "My SaaS application"
enabled: false
...
environments:
dev:
title: "Development Environment"
us-west-2:
applications:
saas:
enabled: true
network:
aws_account: paco.ref accounts.dev
prod:
title: "Production Environment"
default:
applications:
saas:
enabled: true
network:
aws_account: paco.ref accounts.prod
us-west-2:
enabled: true
eu-central-1:
enabeld: true
The scopes available for this NetworkEnvironment are:
netenv.saas.dev
netenv.saas.dev.us-west-2
netenv.saas.prod
netenv.saas.prod.us-west-2
netenv.saas.prod.eu-central-1
After the NetworkEnvironment and Environment, the next component in the scope is the Region. If you do not specify a Region and you can have configured your Environments to belong to more than one region, Paco will apply the scope to all regions in that Environment.
You can drill down deeper than a Region. You may just want to update a single Application, which you can
select with the applications
name and the name of the application:
netenv.saas.prod.us-west-2.applications.saas
Within an Application you can scope even deeper and select only a ResourceGroup or a single Resource:
netenv.saas.prod.us-west-2.applications.saas.groups.cicd
netenv.saas.prod.us-west-2.applications.saas.groups.web.resources.server
Going this deep in the netenv scope is possible, but if you are trying to update some resources but not others,
consider using the change_protected: true
configuration. This field can be applied to any Resource and if set
then Paco will never attempt to make any modifications to it:
saas:
title: "My Saas App"
enabled: false
groups:
web:
type: Application
enabled: true
order: 10
resources:
servers:
type: ASG
# Tell Paco to never touch this resource
change_protected: true
resource scope¶
The resource scope is used to select global resources.
You must specify a minimum of a global Resource type and you must have a YAML file for that type:
resource.codecommit
resource.ec2
These would scope to resource/codecommit.yaml
and resource/ec2.yaml
respectively. For most use cases,
you will want to apply changes to all configuration in a global resource and you can not specify deeper scopes.
A few resources allow for deeper scoping - however, unless you have a very large Resource file, it’s encouraged to simply scope the entire file:
CloudTrail resources in resource/cloudtrail.yaml
:
resource.cloudtrail # applies to all CloudTrails
resource.cloudtrail.trails # also applies to all CloudTrails
resource.cloudtrail.trails.<trail-name> # select a single CloudTrail
EC2 resources in resource/ec2.yaml
:
resource.ec2 # applies to all EC2 Keypairs
resource.ec2.keypairs # also applies to all EC2 Keypairs
resource.ec2.keypairs.<my-keypair> # select a single Keypair
IAM resources in resource/iam.yaml
:
resource.iam # applies to all IAM Users
resource.iam.users # also applies to all IAM Users
resource.iam.users.<my-user> # select a single IAM User
service scope¶
The service scope is used to select Paco extension resources.
You must specify a minimum of a global Resource type and you must have a YAML file for that type:
service.patch
service.security
Typically you will only scope a complete add-on, but it is possible for an add-on to implement deeper scopes. Consult the add-on documentation directly.