CLI (Command Line Interface)

The seedfarmer CLI provides the primary way to interface with the orchestration framework that manages a deploymement with AWS CodeSeeder. It is used by CICD pipelines and individual users to:

deploy code (modules) via a deployment and manifest

fetch metadata related to currently deployed modules

destroy deployments

apply changes to deployments (via a GitOps model)

HTTP Proxy Support

SeedFarmer does support the use of an HTTP-Proxy. It is invoked via setting an environment variable in the context of where the CLI is being invoked. SeedFarmer always leverages HTTPS for its boto3 invocations, so be sure to set the proper parameter.

The parameter we recognize is HTTPS_PROXY . To set it for your runtime, you can do the folllowing (prior to invoking the CLI):

export HTTPS_PROXY=https://<server>:<port>

For example, my server DNS is mygreatserver.com and is listening on port 8899

export HTTPS_PROXY=http://mygreatserver.com:8899

In the above example, you will notice that my proxy is NOT over HTTPS….but the HTTPS_PROXY variable is being set. This is correct, as SeedFarmer is leverging HTTPS for is invocation, regardless of your proxy configuration (it is up to you to determine the proper endpoint).

NOTE: if you run the SeedFarmer CLI with the –debug flag, you can see what the proxy is being configured for:

[2023-05-11 12:54:48,392 | DEBUG | _service_utils.py: 32 | MainThread ] Proxies Configured: {'http': None, 'https': 'http://mygreatserver:8899'}

Summary of Commands

seedfarmer apply

Apply manifests to a SeedFarmer managed deployment

seedfarmer apply [OPTIONS] SPEC

Options

--profile <profile>: The AWS profile used to create a session to assume the toolchain role

--region <region>: The AWS region used to create a session to assume the toolchain role

--qualifier <qualifier>: A qualifier to use with the seedfarmer roles. Use only if bootstrapped with this qualifier

--env-file <env_files>: A relative path to the .env file to load environment variables from. Multple files can be passed in by repeating this flag, and the order will be preserved when overriding duplicate values.

--debug, --no-debug

Enable detailed logging.

Default:: False

--dry-run, --no-dry-run

Apply but do not execute….

Default:: False

--show-manifest, --no-show-manifest

Write out the generated deployment manifest to console

Default:: False

--enable-session-timeout, --disable-session-timeout

Enable boto3 Session timeouts. If enabled, boto3 Sessions will be reset on the timeout interval

Default:: False

--session-timeout-interval <session_timeout_interval>

If –enable-session-timeout, the interval, in seconds, to reset boto3 Sessions

Default:: 900

--update-seedkit, --no-update-seedkit

Force SeedFarmer to update the SeedKit when invoked

Default:: False

--update-project-policy, --no-update-project-policy

Force SeedFarmer to update the deployed Project Policy when invoked

Default:: False

Arguments

SPEC: Required argument

seedfarmer destroy

Destroy a SeedFarmer managed deployment

seedfarmer destroy [OPTIONS] DEPLOYMENT

Options

--dry-run, --no-dry-run

Apply but do not execute….

Default:: False

--show-manifest, --no-show-manifest

Write out the generated deployment manifest

Default:: False

--profile <profile>: The AWS profile used to create a session to assume the toolchain role

--region <region>: The AWS region used to create a session to assume the toolchain role

--qualifier <qualifier>: A qualifier to use with the seedfarmer roles. Use only if bootstrapped with this qualifier

--env-file <env_files>: A relative path to the .env file to load environment variables from. Multple files can be passed in by repeating this flag, and the order will be preserved when overriding duplicate values.

--debug, --no-debug

Enable detailed logging.

Default:: False

--enable-session-timeout, --disable-session-timeout

Enable boto3 Session timeouts. If enabled, boto3 Sessions will be reset on the timeout interval

Default:: False

--session-timeout-interval <session_timeout_interval>

If –enable-session-timeout, the interval, in seconds, to reset boto3 Sessions

Default:: 900

--remove-seedkit, --no-remove-seedkit

Delete the seedkit after destroy of deployment. NOTE: this will forcibly remove the seedkit for ALL deployments of this project. Use with CAUTION. If you are unsure, do not use this flag.

Default:: False

Arguments

DEPLOYMENT: Required argument

seedfarmer list dependencies

List all dependencies of a module

seedfarmer list dependencies [OPTIONS]

Options

-d, --deployment <deployment>: Required The Deployment Name

-g, --group <group>: Required The Group Name

-m, --module <module>: Required The Module Name

-p, --project <project>: Project identifier

--profile <profile>: The AWS profile used to create a session to assume the toolchain role

--region <region>: The AWS region used to create a session to assume the toolchain role

--qualifier <qualifier>: A qualifier to use with the seedfarmer roles. Use only if bootstrapped with this qualifier

--env-file <env_files>: A relative path to the .env file to load environment variables from. Multple files can be passed in by repeating this flag, and the order will be preserved when overriding duplicate values.

--debug, --no-debug

Enable detailed logging.

Default:: False

seedfarmer list deployspec

List the stored deployspec of a module

seedfarmer list deployspec [OPTIONS]

Options

-d, --deployment <deployment>: Required The Deployment Name

-g, --group <group>: Required The Group Name

-m, --module <module>: Required The Module Name

-p, --project <project>: Project identifier

--profile <profile>: The AWS profile used to create a session to assume the toolchain role

--region <region>: The AWS region used to create a session to assume the toolchain role

--qualifier <qualifier>: A qualifier to use with the seedfarmer roles. Use only if bootstrapped with this qualifier

--env-file <env_files>: A relative path to the .env file to load environment variables from. Multple files can be passed in by repeating this flag, and the order will be preserved when overriding duplicate values.

--debug, --no-debug

Enable detailed logging.

Default:: False

seedfarmer list moduledata

Fetch the module metadata

seedfarmer list moduledata [OPTIONS]

Options

-d, --deployment <deployment>: Required The Deployment Name

-g, --group <group>: Required The Group Name

-m, --module <module>: Required The Module Name

-p, --project <project>: Project identifier

--profile <profile>: The AWS profile used to create a session to assume the toolchain role

--region <region>: The AWS region used to create a session to assume the toolchain role

--qualifier <qualifier>: A qualifier to use with the seedfarmer roles. Use only if bootstrapped with this qualifier

--export-local-env, --no-export-local-env

Print the moduledata as env parameters for local development support INSTEAD of json (default is FALSE)

Default:: False

--env-file <env_files>: A relative path to the .env file to load environment variables from. Multple files can be passed in by repeating this flag, and the order will be preserved when overriding duplicate values.

--debug, --no-debug

Enable detailed logging.

Default:: False

seedfarmer list allmoduledata

Fetch ALL module metadata in the deployment as a dict

seedfarmer list allmoduledata [OPTIONS]

Options

-d, --deployment <deployment>: Required The Deployment Name

-p, --project <project>: Project identifier

--profile <profile>: The AWS profile used to create a session to assume the toolchain role

--region <region>: The AWS region used to create a session to assume the toolchain role

--qualifier <qualifier>: A qualifier to use with the seedfarmer roles. Use only if bootstrapped with this qualifier

--env-file <env_files>: A relative path to the .env file to load environment variables from. Multple files can be passed in by repeating this flag, and the order will be preserved when overriding duplicate values.

--debug, --no-debug

Enable detailed logging.

Default:: False

seedfarmer list modules

List the modules in a deployment

seedfarmer list modules [OPTIONS]

Options

-d, --deployment <deployment>: Required The Deployment Name

-p, --project <project>: Project identifier

--profile <profile>: The AWS profile used to create a session to assume the toolchain role

--region <region>: The AWS region used to create a session to assume the toolchain role

--qualifier <qualifier>: A qualifier to use with the seedfarmer roles. Use only if bootstrapped with this qualifier

--env-file <env_files>: A relative path to the .env file to load environment variables from. Multple files can be passed in by repeating this flag, and the order will be preserved when overriding duplicate values.

--debug, --no-debug

Enable detailed logging.

Default:: False

seedfarmer list deployments

List the deployments in this account

seedfarmer list deployments [OPTIONS]

Options

-p, --project <project>: Project identifier

--profile <profile>: The AWS profile used to create a session to assume the toolchain role

--region <region>: The AWS region used to create a session to assume the toolchain role

--qualifier <qualifier>: A qualifier to use with the seedfarmer roles. Use only if bootstrapped with this qualifier

--debug, --no-debug

Enable detailed logging.

Default:: False

seedfarmer list buildparams

Fetch the environment params of an executed build. This is to help with local development efforts.

seedfarmer list buildparams [OPTIONS]

Options

-d, --deployment <deployment>: Required The Deployment Name

-g, --group <group>: Required The Group Name

-m, --module <module>: Required The Module Name

--build-id <build_id>: Required The Build ID to fetch this info for

-p, --project <project>: Project identifier

--profile <profile>: The AWS profile used to create a session to assume the toolchain role

--region <region>: The AWS region used to create a session to assume the toolchain role

--qualifier <qualifier>: A qualifier to use with the seedfarmer roles. Use only if bootstrapped with this qualifier

--export-local-env, --no-export-local-env

Print the moduledata as env parameters for local development support INSTEAD of json (default is FALSE)

Default:: False

--env-file <env_files>: A relative path to the .env file to load environment variables from. Multple files can be passed in by repeating this flag, and the order will be preserved when overriding duplicate values.

--debug, --no-debug

Enable detailed logging.

Default:: False

seedfarmer list schema

Generate the schema that SeedFarmer uses for manifest objects. This will return a formatted string of the schema that can be piped to a file.

seedfarmer list schema [OPTIONS]

seedfarmer bootstrap toolchain

Bootstrap a Toolchain account.

seedfarmer bootstrap toolchain [OPTIONS]

Options

-p, --project <project>: Project identifier

-t, --trusted-principal <trusted_principal>: ARN of Principals trusted to assume the Toolchain Role. This can be used multiple times to create a list.

-b, --permissions-boundary <permissions_boundary>: ARN of a Managed Policy to set as the Permission Boundary on the Toolchain Role

--as-target, --not-as-target

Optionally also bootstrap the account as a Target account

Default:: False

--synth, --no-synth

Synthesize a CFN bootstrap template only…do not deploy

Default:: False

--profile <profile>: The AWS profile to use to initiate a session

--region <region>: AWS region to use to initiate a session

--qualifier <qualifier>: A qualifier to append to toolchain role (alpha-numeric char max length of 6). If used, it MUST be used on every seedfarmer command.

-pa, --policy-arn <policy_arn>: ARN of existing Policy to attach to Target Role (Deploymenmt Role) This can be use multiple times, but EACH policy MUST be valid in the Target Account. The –as-target flag must be used if passing in policy arns as they are applied to the Deployment Role only.

--debug, --no-debug

Enable detail logging

Default:: False

seedfarmer bootstrap target

Bootstrap a Target account.

seedfarmer bootstrap target [OPTIONS]

Options

-p, --project <project>: Project identifier

-t, --toolchain-account <toolchain_account>: Required Account Id of the Toolchain account trusted to assume the Target account’s Deployment Role

-b, --permissions-boundary <permissions_boundary>: ARN of a Managed Policy to set as the Permission Boundary on the Toolchain Role

--synth, --no-synth

Synthesize a CFN template only…do not deploy

Default:: False

--profile <profile>: The AWS profile to use to initiate a session

--region <region>: AWS region to use to initiate a session

--qualifier <qualifier>: A qualifier to append to target role (alpha-numeric char max length of 6). If used on the toolchain account, it should be used here!

-pa, --policy-arn <policy_arn>: ARN of existing Policy to attach to Target Role (Deploymenmt Role) This can be use multiple times to create a list, but EACH policy MUST be valid in the Target Account

--debug, --no-debug

Enable detail logging

Default:: False

seedfarmer init module

Initialize a new module

seedfarmer init module [OPTIONS]

Options

-g, --group-name <group_name>: The group the module belongs to. The group is created if it doesn’t exist

-m, --module-name <module_name>: Required The module name

-mt, --module-type <module_type>: The type of module code deployed…only ‘cdkv2’ is accepted if used here

-t, --template-url <template_url>: The template URL. If not specified, the default template repo is https://github.com/awslabs/seed-farmer

--debug, --no-debug

Enable detail logging

Default:: False

seedfarmer init project

Initialize a project. Make sure seedfarmer.yaml is present in the same location you execute this command!!

seedfarmer init project [OPTIONS]

Options

-t, --template-url <template_url>: The template URL. If not specified, the default template repo is https://github.com/awslabs/seed-farmer

seedfarmer projectpolicy synth

Synth a Project Policy from seed-farmer.

seedfarmer projectpolicy synth [OPTIONS]

Options

--debug, --no-debug

Enable detail logging

Default:: False

seedfarmer metadata convert

Convert the CDK Output of the module to SeedFarmer Metadata. This command is meant to be run in the deployspec only!!!

seedfarmer metadata convert [OPTIONS]

Options

-jq, --jq-path <jq_path>: A jq-compliant path to apply to a cdk-output (json) file

-f, --json-file <json_file>: Relative path to a cdk-output file (defautls to cdk-exports.json)

seedfarmer metadata add

Add Output K,V to the Metadata. This command is meant to be run in the deployspec only!!!

seedfarmer metadata add [OPTIONS]

Options

-k, --key <key>: The key of a key-value pair

-v, --value <value>: The value of a key-value pair

-j, --jsonstring <jsonstring>: JSON-compliant string to add in a stringified format

seedfarmer metadata depmod

Get the Full Name of the Module. This command is meant to be run in the deployspec only!!!

seedfarmer metadata depmod [OPTIONS]

seedfarmer metadata paramvalue

Get the parameter value based on the suffix. This command is meant to be run in the deployspec only!!!

seedfarmer metadata paramvalue [OPTIONS]

Options

-s, --suffix <suffix>: Required A jq-compliant path to apply to a cdk-output (json) file

seedfarmer remove moduledata

Remove all SSM parameters tied to the module. This command is meant to be run by seedfarmer ONLY!!! It is run within the context of the build job. Do not use this unless you are sure of the ramifications!

seedfarmer remove moduledata [OPTIONS]

Options

-d, --deployment <deployment>: Required The Deployment Name

-g, --group <group>: Required The Group Name

-m, --module <module>: Required The Module Name

-p, --project <project>: Project identifier

--profile <profile>: The AWS profile used to create a session.

--region <region>: The AWS region used to create a session.

--qualifier <qualifier>: A qualifier to use with the seedfarmer roles

--target-account-id <target_account_id>: Account Id to remove module data from, if specifed –target-region is required

--target-region <target_region>: Region to remove module data from, if specifed –target-account-id is required

--debug, --no-debug

Enable detailed logging.

Default:: False

seedfarmer store deployspec

Store/Update a deployspec of a currently deployed module. Use this if you cannot destroy a deployed module because of a defect in the the destroy portion of the deployspec. USE WITH CAUTION as the existing deployspec gets overwritten and is NOT recoverable.

seedfarmer store deployspec [OPTIONS]

Options

-d, --deployment <deployment>: Required The Deployment Name

-g, --group <group>: Required The Group Name

-m, --module <module>: Required The Module Name

--path <path>: Required The relative module path (ex. modules/optionals/networking) - DO NOT PASS IN filename deployspec.yaml

-p, --project <project>: Project identifier

--profile <profile>: The AWS profile used to create a session to assume the toolchain role

--region <region>: The AWS region used to create a session to assume the toolchain role

--qualifier <qualifier>: A qualifier to use with the seedfarmer roles. Use only if bootstrapped with this qualifier

--target-account-id <target_account_id>: Account Id of the target accout to store deployspec, if specifed –target-region is required You SHOULD NOT use this parameter as this command will leverage the SeedFarmer session manager! It is meant for development purposes.

--target-region <target_region>: Region of the target accout to store deployspec, if specifed –target-account-id is required You SHOULD NOT use this parameter as this command will leverage the SeedFarmer session manager! It is meant for development purposes.

--debug, --no-debug

Enable detailed logging.

Default:: False

seedfarmer store moduledata

CAT or pipe in a json or yaml object. This command is meant to be run by seedfarmer ONLY!!! It is run within the context of the build job. Do not use this unless you are sure of the ramifications!

seedfarmer store moduledata [OPTIONS]

Options

-d, --deployment <deployment>: Required The Deployment Name

-g, --group <group>: Required The Group Name

-m, --module <module>: Required The Module Name

-p, --project <project>: Project identifier

--profile <profile>: The AWS profile used to create a session to assume the toolchain role

--region <region>: The AWS region used to create a session to assume the toolchain role

--qualifier <qualifier>: A qualifier to use with the seedfarmer roles. Use only if bootstrapped with this qualifier

--target-account-id <target_account_id>: Account Id of the target accout to store module metadata, if specifed –target-region is required

--target-region <target_region>: Region of the target accout to store module metadata, if specifed –target-account-id is required

--debug, --no-debug

Enable detailed logging.

Default:: False

seedfarmer store md5

CAT or pipe in a string. This command is meant to be run by seedfarmer ONLY!!!

seedfarmer store md5 [OPTIONS]

Options

-d, --deployment <deployment>: Required The Deployment Name

-g, --group <group>: Required The Group Name

-m, --module <module>: Required The Module Name

-t, --type <type>: Required The kind of MD5: bundle or spec

-p, --project <project>: Project identifier

--profile <profile>: The AWS profile used to create a session to assume the toolchain role

--region <region>: The AWS region used to create a session to assume the toolchain role

--qualifier <qualifier>: A qualifier to use with the seedfarmer roles. Use only if bootstrapped with this qualifier

--target-account-id <target_account_id>: Account Id of the target accout to store md5, if specifed –target-region is required

--target-region <target_region>: Region of the target accout to store md5, if specifed –target-account-id is required

--debug, --no-debug

Enable detailed logging.

Default:: False