Apigee Management API command-line interface with multi-factor authentication (MFA) and single sign-on (SSO)/SAML support
Project description
Welcome to the Apigee Management API command-line interface!
Usage: apigee [OPTIONS] COMMAND [ARGS]...
Welcome to the Apigee Management API command-line interface!
Docs: https://mdelotavo.github.io/apigee-cli/
PyPI: https://pypi.org/project/apigeecli/
GitHub: https://github.com/mdelotavo/apigee-cli
Options:
-V, --version Show the version and exit.
-h, --help Show this message and exit.
Commands:
apiproducts API products enable you to bundle and distribute your APIs...
apis The proxy APIs let you perform operations on API proxies,...
apps Management APIs available for working with developer apps.
auth Custom authorization commands.
backups Download configuration files from Apigee that can later be...
caches A lightweight persistence store that can be used by...
configure Configure Apigee Edge credentials.
deployments API proxies that are actively deployed in environments on...
developers Developers implement client/consumer apps and must be...
keystores A list of URIs used to create, modify, and delete
keystores...
keyvaluemaps Key/value maps at the environment scope can be accessed by...
maskconfigs Specify data that will be filtered out of trace sessions.
permissions Permissions for roles in an organization on Apigee Edge.
references References in an organization and environment.
sharedflows You can use the following APIs to manage shared flows and...
targetservers TargetServers are used to decouple TargetEndpoint...
userroles Roles for users in an organization on Apigee Edge.
virtualhosts A named network configuration (including URL) for an...
This is not an officially supported Google product, and is not affiliated with Apigee or Google in any way.
Please note that this CLI is still highly experimental and may change significantly based on client needs.
Why does this exist?
Apigee CLI is a user-friendly command-line interface to the Apigee Edge Management API providing features that automate steps that are too cumbersome to perform manually or are non-existent in existing tools such as multi-factor authentication (MFA) and single sign-on (SSO)/SAML. It is intended for general administrative use from your shell, as a package for developers, and to support automation for common development tasks, such as test automation or Continuous Integration/Continuous Deployment (CI/CD).
We built and use the Apigee CLI to implement and distribute features that allow our clients to manage CI/CD and perform self-service operations and promote our DevOps workflows in ways that are not supported by official tools. Additionally, we constantly add new features and make improvements to the CLI to make it more user-friendly based on client needs and feedback.
The Apigee CLI also supports the ability to load third-party plugins (to be documented) as additional commands which enables us (and third-party developers) to distribute their own commands for very specific use cases which may not even require any interaction with the Apigee Management API, while being able to leverage the command-line interface without any knowledge of the CLI internals.
Apigee Corporation provides their own CLI for the Apigee Management API known as apigeetool-node. This is a comprehensive and well-supported tool which can also be used as an SDK to orchestrate tasks and may be more than suitable for your needs. If however, you have certain use cases that cannot be satisfied by this tool, such as those requiring a more simplified use of CLI commands for CI/CD usage, then the Apigee CLI may have what you need.
Example use cases that are too specialised for official tools are (to be) documented below.
Making CI/CD work on SSO/SAML and MFA enabled Apigee Edge organizations
This section will describe how we use the Apigee CLI to perform CI/CD and enable clients to access the Apigee Management APIs when SSO/SAML or MFA is enabled organization wide.
Provisioning custom API Proxy deployments with a single command
This section will describe how we use the Apigee CLI to enable clients to generate proxies from proxy templates on GitLab (enforcing conventions and best practices) and deploy them, all with a single command.
Encrypting KVMs at rest and decrypting via CI/CD
This section will describe how we use the Apigee CLI to encrypt KVM secrets at rest and later decrypt those secrets and deploy them to Apigee Edge via CI/CD.
Distributing and developing third-party plugins as commands
This section will describe how we use the Apigee CLI to distribute custom commands for clients, and even give them the ability to develop their own commands that can be dynamically loaded into the CLI.
Taking snapshots of Apigee Edge
This section will describe how we use the Apigee CLI to take snapshots of things on Apigee Edge via scheduled CI/CD pipelines.
Using resource permissions as templates
This section will describe how we use the Apigee CLI to distribute resource permission templates that can be used to automate creation of resource permissions across user roles.
Installation
The easiest way to install apigee-cli is to use pip in a virtualenv:
$ pip install apigeecli
or, if you are not installing in a virtualenv, to install globally:
$ sudo pip install apigeecli
or for your user:
$ pip install --user apigeecli
If you have the apigee-cli installed and want to upgrade to the latest version you can run:
$ pip install --upgrade apigeecli
Getting Started
Before using apigee-cli, you need to tell it about your Apigee Edge credentials. You can do this in three ways:
Environment variables
Config file
Command-line arguments
The quickest way to get started is to run the apigee configure command:
$ apigee configure Apigee username (email) []: my_email Apigee password []: my_pass Apigee MFA key (optional) []: my_key Identity zone name (to support SAML authentication) []: Use OAuth, no MFA (optional)? [y/N]: n Default Apigee organization (recommended) []: my_org Default team/resource prefix (optional) []:
You can also do the same thing using command-line arguments:
$ apigee configure -P default -u <my_email> -p <my_pass> -o <my_org> -mfa '' -z '' --no-token --prefix ''
You may need to specify empty strings as above. Also note the --prefix option. This option will filter the output of some commands, such as the list type commands, by the prefix which may be useful to some people, but if you want to avoid confusion just keep this value empty. You can also explicitly specify the --prefix for those commands if you need it on the fly.
To use environment variables, do the following:
$ export APIGEE_USERNAME=<my_email> $ export APIGEE_PASSWORD=<my_pass> $ export APIGEE_MFA_SECRET=<my_key> $ export APIGEE_ZONENAME=<my_zonename> $ export APIGEE_IS_TOKEN=<bool> $ export APIGEE_ORG=<my_org> $ export APIGEE_CLI_PREFIX=<my_prefix>
To use the configuration file, create an INI formatted file like this:
[default] username = my_email org = my_org mfa_secret = my_key prefix = my_prefix password = my_pass [produser] org = my_org username = my_email password = my_pass mfa_secret = my_key
and place it in ~/.apigee/credentials.
As you can see, you can have multiple profiles defined in the configuration file. You can then specify which profile to use by using the -P/--profile option. If no profile is specified the default profile is used.
Using SAML authentication
If you specified an Identity zone name (to support SAML authentication) during setup, the CLI will automatically use SAML authentication. If you are not currently signed in by your identity provider, you will be prompted to sign in:
$ apigee apis list SSO authorization page has automatically been opened in your default browser. Follow the instructions in the browser to complete this authorization request. If your browser did not automatically open, go to the following URL and sign in: https://{zoneName}.login.apigee.com/passcode then copy the Temporary Authentication Code. Please enter the Temporary Authentication Code:
zoneName will be the Identity zone name you previously configured.
Refer to the official Apigee documentation to learn more about how to Access the Edge API with SAML.
Deploy API Proxy bundles
You can also deploy API proxy bundles to Apigee.
This command is an enhanced version of the Apigee API Proxy Deploy Tool.
It supports a bunch of useful features such as MFA, SAML, seamless deployments and automatic handling of missing and broken deployments.
$ apigee apis deploy -n API_NAME -e ENVIRONMENT -d DIRECTORY_WITH_APIPROXY
Some notable options:
Deployment options: [mutually_exclusive] The deployment options -i, --import-only / -I, --no-import-only import only and not deploy -s, --seamless-deploy / -S, --no-seamless-deploy seamless deploy the bundle
Cleaning up undeployed revisions
If deploying via CI/CD you may end up with a lot of undeployed revisions. In this case, you can make use of the clean command to delete all undeployed revisions.
$ apigee apis clean -n API_NAME
You can also specify to keep the last few revisions:
$ apigee apis clean -n API_NAME --save-last 10
To only show which revisions will be deleted but not actually delete anything, use the following option:
--dry-run / --no-dry-run show revisions to be deleted but do not delete
Push commands
Some commands support the push subcommand which combines API calls to manage the creation, update and sometimes deletion of resources using a single command.
Push commands read JSON from a file and can be invoked like so:
$ apigee keyvaluemaps push -e <env> -f <file_path.json>
This will create the KVM if it does not exist, and update it if it does.
More Commands
This will be documented soon.
Third-party plugins
This will be documented soon.
Getting Help
For further questions, feel free to contact us at hello@darumatic.com or contact matthew@darumatic.com.
Next Steps
You may want to make use of our Apigee CI/CD Docker releases:
$ docker pull darumatic/apigee-cicd
Disclaimer
This is not an officially supported Google product.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for apigeecli-0.46.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 39e0bb1a1eef8e05ce2819083d0145ac343497c77a080b5e0068c60fbbddd05f |
|
MD5 | 6abb126cb2ba65479ae1233663a32e40 |
|
BLAKE2b-256 | 73b04822e272da9ac9ac0889cd4490dd1546742fe2d931f8290ebf0f3cb02aff |