cloudify 3.1

Cloudify CLI

Cloudify CLI
============

Command line interface for
`Cloudify <https://github.com/cloudify-cosmo/cloudify-manager>`__

- `Deploying your first application -
Walkthrough <#deploying-your-first-application---walkthrough>`__
- `Providers <#providers>`__
- `Currently Supported Providers <#currently-supported-providers>`__
- `Creating a new provider
extension <#creating-a-new-provider-extension>`__
- `Working-Directory Settings and
Configurations <#working-directory-settings-and-configurations>`__
- `Commands Docs <#commands-docs>`__

--------------

Deploying your first application - Walkthrough
----------------------------------------------

**1. Installing the CLI and a provider extension:** - Clone this
repository: ``git clone https://github.com/cloudify-cosmo/cloudify-cli``
- Run pip install:
``pip install -r cloudify-cli/requirements.txt cloudify-cli/`` - Clone
openstack provider CLI:
``git clone https://github.com/cloudify-cosmo/cloudify-openstack-provider``
- Run pip install:
``pip install -r cloudify-openstack-provider/requirements.txt cloudify-openstack-provider/``

NOTES: - After installing the cli you can run the
"activate\_cfy\_bash\_completion" script which will permanently add bash
completion to you shel and then follow the instructions or run "eval
"$(register-python-argcomplete cfy)"" if you want to activate bash
completion for your active shell only)

**NOTE: you can run CLI commands with the -v (verbosity) flag to view
tracebacks and additional debug info.**

**2. Initializing:** - Cd into your favorite working directory and
initialize Cloudify for some provider: ``cfy init openstack``

- Edit the autogenerated provider-specific config file
"*cloudify-config.yaml*\ " - update its mandatory (non-commented)
settings as needed. (For more information about the configuration
files parameters used in this example, view the `Cloudify-Openstack
readme <https://github.com/cloudify-cosmo/cloudify-openstack-provider/blob/develop/README.md>`__)

- Bootstrap cloudify on Openstack: ``cfy bootstrap`` This could take a
bit of time to finish... Looking for something to do in the
meanwhile? http://dynamic.xkcd.com/random/comic/

**NOTE: running ``cfy bootstrap`` with the --dev-mode flag, will allow
you to use different branches when bootstrapping the manager (see the
provider's cloudify-config.defaults.yaml file for configuration
options.)**

**3. Deploying your application:** - Upload your blueprint:
``cfy blueprints upload my-app/blueprint.yaml -b hello_world`` (Don't
have a blueprint? You can download a sample one
`here <https://github.com/CloudifySource/cloudify-hello-world/tree/develop/openstack>`__).

- Create a deployment of the blueprint:
``cfy deployments create -b hello_world -d my-deployment``

- Execute an install operation on the deployment:
``cfy deployments execute install -d my-deployment``

This will install your deployment - all you have left to do is sit back
and watch the events flow by until the deployment is complete.

**4. Fetching execution events:** - List deployment executions:
``cfy executions list -d my-deployment``

- Fetch execution events by execution id:
``cfy events --execution-id f6269ccf-1243-439e-b779-c0f8d06a9894``

--------------

Providers
---------

A provider is any platform which allows for the creation and
bootstrapping of a management server (e.g. Openstack). The CLI can work
with any provider once the appropriate extension has been installed. A
provider extension is provider-specific code which handles
environment-related operations such as bootstrap and teardown.

Note that the CLI can be used even without the installation of any
providers - if you already possess a bootstrapped management server, you
may simply direct the CLI to work with that server
(``cfy use <management-ip>``), and you can then issue any of the CLI
commands to that server

Currently Supported Providers:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- `Openstack <https://github.com/cloudify-cosmo/cloudify-openstack-provider/tree/develop>`__
- `Vagrant <https://github.com/cloudify-cosmo/cloudify-vagrant-provider/tree/develop>`__

Creating a new provider extension:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Provider extensions are simply Python modules which adhere to certain
conventions and implement a certain interface.

By convention, the module name is called "*cloudify\_.py*\ ". While any
name is viable in practice, the CLI **cfy init** command, which receives
a '*provider*\ ' parameter, is set to first search for a module named by
the convention, and only search for the exact '*provider*\ ' value given
if such a module was not found.

Every provider extention is expected to implement the following
interface:

- **init**\ (*target\_directory*, *reset\_config*,
*is\_verbose\_output=False*)

- **Description**: This method is used to create any required
configuration files at the given target directory, as well as make
any other initializations required by the specific provider.
- **Parameters:**:
- *target\_directory* - Target directory for configuration files, if
any.
- *reset\_config* - A boolean describing whether overwriting
existing configuration files is allowed.
- *is\_verbose\_output* - A flag for setting verbose output
- **Returns:**: False if a configuration file already exists and
reset\_config is False; True otherwise.

- **bootstrap**\ (*config\_file\_path=None*,
*is\_verbose\_output=False*, *bootstrap\_using\_script=False*,
*keep\_up=False*, "dev\_mode=False\*")

- **Description**: This method is used to set up the management
server as well as the environment (e.g. network) in which it
resides. It is currently also responsible for bootstrapping the
server as a management server. This method is also in charge of
creating the provider-context object, which will be stored on both
the management server and locally, and will be retrieved and used
upon a call to the teardown command - making it useful for storing
bootstrap information which will be needed at the teardown stage.
- **Parameters**:
- *config\_file\_path* - A path to an appropriate configuration file
to be used in the bootstrap process. If one is required yet not
passed, the Provider is expected to assume this command is called
from the same path from which "init" was called, and search for
the relevant file in the current directory.
- *is\_verbose\_output* - A flag for setting verbose output,
- *bootstrap\_using\_script* - A flag indicating that bootstrap will
be performed via a script (rather than a package. the script is
provided within the provider's code).
- *keep\_up* - A flag indicating that even if bootstrap fails, the
instance will remain running.
- *--dev-mode* - A flag indicating that bootstrap will be run in
dev-mode, allowing to choose specific branches to run with.
- **Returns**: A 2-tuple: The IP of the bootstrapped management
server, and the provider context object.

- **teardown**\ (*provider\_context*, *ignore\_conflicts=False*,
*config\_path=None*, *is\_verbose\_output=False*)

- **Description**: This method is used to tear down the management
server, as well as any environment objects related to the server
which will no longer be of use.
- **Parameters**:
- *provider\_context* - The provider context object which the
provider creates at bootstrap stage.
- *ignore\_conflicts* - A flag for ignoring detected conflicts,
allowing the teardown operation to continue and delete whatever
resources which there aren't any conflicts on.
- *config\_path* - A path to an appropriate configuration file to be
used in the bootstrap process. If one is required yet not passed,
the Provider is expected to assume this command is called from the
same path from which "init" was called, and search for the
relevant file in the current directory.
- *is\_verbose\_output* - A flag for setting verbose output
- **Returns**: None.

Another convention worth mentioning is one used for the Provider's
**init** method: While a Provider may create any number of
provider-specific configuration files on init (or none at all) in any
format it so chooses, the standard is for it to create a single
configuration file in YAML format named "*cloudify-config.yaml*\ ".
Additionally, it's recommended that all default values in the file are
commented out, for ease of use.

--------------

Working-Directory Settings and Configurations
---------------------------------------------

When running the CLI **cfy init** command, a "*.cloudify*\ " file will
be created in the target directory. All local settings (such as the
default management server and aliases) are stored in that file, and only
take effect when using the CLI from the target directory.

Additionally to creating the "*.cloudify*\ " file, the **cfy init**
command will usually also create a provider-specific configuration file
named "*cloudify-config.yaml*\ ", which will later be used by the **cfy
bootstrap** command. This, however, is merely a convention, one which
various providers may choose not to follow.

Note: If the Cloudify working directory is also a git repository, it's
recommended to add "*.cloudify*\ " to the .gitignore file.

--------------

Commands Docs
-------------

re **Command:** status

**Description:** queries the status of the management server

**Usage:** ``cfy status [-t, --management-ip <ip>] [-v, --verbosity]``

**Parameters**:

- management-ip: the management-server to use (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:** ``cfy status``

--------------

**Command:** use

**Description:** defines a default management server to work with

**Usage:**
``cfy use <management_ip> [-a, --alias <alias>] [-f, --force] [-v, --verbosity]``

**Parameters**:

- management\_ip: the management-server to define as the default
management server
- alias: a local alias for the given management server address
(Optional)
- force: a flag indicating authorization to overwrite the alias
provided if it's already in use (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:** ``cfy use 10.0.0.1 -a my-mgmt-server``

--------------

**Command:** init

**Description:** initializes a cloudify working directory for a given
provider

**Usage:**
``cfy init <provider> [-t, --target-dir <dir>] [-r, --reset-config] [-v, --verbosity]``

**Parameters**:

- provider: the cloudify provider to use for initialization
- target-dir: the directory that will be used as the cloudify working
directory (Optional)
- reset-config: a flag indicating overwriting existing configuration is
allowed (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:** ``cfy init openstack``

--------------

**Command:** bootstrap

**Description:** bootstraps cloudify on the current provider

**Usage:**
``cfy bootstrap [-c, --config-file <file>] [-v, --verbosity]``

**Parameters**:

- config-file: path to the config file (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:** ``cfy bootstrap``

--------------

**Command:** teardown

**Description:** tears down the management-server, as well as any local
aliases under its context

**Usage:**
``cfy teardown [-c, --config-file] [-f, --force] [-fv, --force-validation] [-fd, --force-deployments] [-t, --management-ip <ip>] [-v, --verbosity]``

**Parameters**:

- config-file: path to the config file (Optional)
- force: a flag indicating confirmation for this irreversable action
(Optional)
- force-validation: A flag indicating confirmation for the provider to
continue with the teardown process even if there are conflicts
detected, allowing whatever resources which there aren't any
conflicts on to be removed (Optional)
- force-deployments: A flag indicating confirmation to continue with
the teardown process even if the management server currently has
active deployments (Optional)
- management-ip: the management-server to use (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:** ``cfy teardown -f``

--------------

**Command:** blueprints upload

**Description:** uploads a blueprint to the management server

**Usage:**
``cfy blueprints upload <blueprint_path> [-b, --blueprint-id <blueprint_id>] [-t, --management-ip <ip>] [-v, --verbosity]``

**Parameters**:

- blueprint\_path: path to the blueprint (yaml file) to upload
- blueprint\_id: a unique id for the uploaded blueprint (Optional, plan
name is used if not provided)
- management-ip: the management-server to use (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:** ``cfy blueprints upload blueprint.yaml``

--------------

**Command:** blueprints list

**Description:** lists the blueprint on the management server, as well
as the blueprints local aliases

**Usage:**
``cfy blueprints list [-t, --management-ip <ip>] [-v, --verbosity]``

**Parameters**:

- management-ip: the management-server to use (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:** ``cfy blueprints list``

--------------

**Command:** blueprints delete

**Description:** deletes the blueprint from the management server

**Usage:**
``cfy blueprints delete [-b, --blueprint-id <blueprint_id>] [-t, --management-ip <ip>] [-v, --verbosity]``

**Parameters**:

- blueprint\_id: the id of the blueprint to delete
- management-ip: the management-server to use (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:** ``cfy blueprints delete -b my-blueprint``

--------------

**Command:** deployments create

**Description:** creates a deployment of a blueprint

**Usage:**
``cfy deployments create [-b, --blueprint-id <blueprint_id>] [-d, --deployment-id <deployment_id>] [-t, --management-ip <ip>] [-v, --verbosity]``

**Parameters**:

- blueprint\_id: the id of the blueprint to deploy
- deployment\_id: a unique id for the created deployment
- management-ip: the management-server to use (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:** ``cfy deployments create -b my-blueprint -d my-deployment``

--------------

**Command:** deployments delete

**Description:** deletes the deployment (and its resources) from the
management server

**Usage:**
``cfy deployments delete [-d, --deployments-id <deployment_id>] [-f, --ignore-live-nodes] [-t, --management-ip <ip>] [-v, --verbosity]``

**Parameters**:

- blueprint\_id: the id of the blueprint to delete
- ignore-live-nodes: a flag determining whether to delete the
deployment even if it still has live nodes (Optional)
- management-ip: the management-server to use (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:** ``cfy deployments delete -d my-deployment``

--------------

**Command:** deployments execute

**Description:** executes an operation on a deployment

**Usage:**
``cfy deployments execute <operation> [-d, --deployment-id <deployment_id>] [-t, --management-ip <ip>] [-v, --verbosity] [--timeout <timeout>] [--force]``

**Parameters**:

- operation: the name of the operation to execute
- deployment\_id: the deployment id on which the operation should be
executed
- management-ip: the management-server to use (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)
- timeout: operation timeout in seconds (Optional, The execution itself
will keep going. It is the CLI that will stop waiting for it to
terminate)
- force: A flag indicating the workflow should execute even if there is
an ongoing execution for the provided deployment (Optional)

**Example:** ``cfy deployments execute install -d my-deployment``

--------------

**Command** deployments list

**Description** Lists deployments on management server

**Usage**
``cfy deployments list [-b, --blueprint-id <blueprint-id>] [-t, --management-ip <ip>] [-v, --verbosity]``

**Parameters**: - blueprint-id: the id of the blueprint to to list
deployments for (Optional, lists all deployments if not provided) -
management-ip: the management-server to use (Optional) -
is\_verbose\_output - A flag for setting verbose output (Optional)

--------------

**Command:** workflows list

**Description:** lists the workflows of a deployment

**Usage:**
``cfy workflows list [-d, --deployment-id <deployment_id>] [-t, --management-ip <ip>] [-v, --verbosity]``

**Parameters**:

- deployment\_id: the id of the deployment whose workflows to list
- management-ip: the management-server to use (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:** ``cfy workflows list -d my-deployment``

--------------

**Command:** executions get

**Description:** gets an execution by its id

**Usage:**
``cfy executions get [-e, --execution-id <execution_id>] [-t, --management-ip <ip>] [-v, --verbosity]``

**Parameters**:

- execution\_id: the id of the execution to get
- management-ip: the management-server to use (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:** ``cfy executions get -e my-execution``

--------------

**Command:** executions list

**Description:** lists the executions of a deployment

**Usage:**
``cfy executions list [-d, --deployment-id <deployment_id>] [-t, --management-ip <ip>] [-v, --verbosity]``

**Parameters**:

- deployment\_id: the id of the deployment whose executions to list
- management-ip: the management-server to use (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:** ``cfy executions list -d my-deployment``

--------------

**Command:** executions cancel

**Description:** Cancels an execution by its id

**Usage:**
``cfy executions cancel [-e, --execution-id <execution_id>] [-f, --force] [-t, --management-ip <ip>] [-v, --verbosity]``

**Parameters**:

- execution\_id: the id of the execution to cancel
- force: A flag indicating authorization to terminate the execution
abruptly rather than request an orderly termination (Optional)
- management-ip: the management-server to use (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:** ``cfy executions cancel -e some-execution-id -f``

--------------

**Command:** events

**Description:** fetches events of an execution

**Usage:**
``cfy events [-h] [-e EXECUTION_ID] [-l, --include-logs] [-t, --management-ip <ip>] [-v, --verbosity]``

**Parameters**:

- execution-id: the id of the execution to fetch events for
- include-logs: determines whether to fetch logs in addition to events
- management-ip: the management-server to use (Optional)
- is\_verbose\_output - A flag for setting verbose output (Optional)

**Example:**
``cfy events --execution-id 92515e66-5c8f-41e0-a361-2a1ad92706b2``