rok-deploy

rok-deploy is the tool that allows automated deployments based on your choices about your specific environment and needs. This section gives an overview of the tool.

Note

Arrikto EKF supports rok-deploy only on AWS environments.

See also

Task Structure

The EKF installation procedure is split into many small standalone guides to make the overall process easier. Similarly, rok-deploy performs small deployment tasks, that each correspond to the respective guide in the EKF installation documentation.

Every deployment task in rok-deploy has a specific structure. At first, you can choose whether to run the task or fast-forward it. In the latter case, rok-deploy assumes you’ve already deployed the necessary resources and will not create them for you (e.g., a Kubernetes cluster). It will still prompt you though for input regarding your existing resources, in order to verify your configuration.

If you choose to run the task, you will have the option to generate and apply manifests. The generate phase configures local state, usually editing local files and committing the changes to the GitOps repository, based on your input. The apply phase, deploys the resources designated by the manifests. You can choose to skip any of the two phases. A common use case is to skip the apply phase, therefore only generating manifests. You can find more information about this use case in the relevant guide.

Finally, before moving to the next deployment task, rok-deploy will perform a verification process to make sure the given resources are valid and the installation can continue.

List Deployment Tasks

You can get information about all the deployment tasks directly via rok-deploy by running:

root@rok-tools:~# rok-deploy --list-tasks

You can select any of the displayed tasks to get more information about it. The information currently available for each task is the following:

  • A description about the functionality that the task provides.
  • A symbolic name, that is, a reference name that is useful for uniquely identifying a task.
  • A list of arguments that rok-deploy accepts and are solely related to the task.
  • A cheat-sheet command for starting the installation directly from the task, in case you’ve already run the previous ones.
  • A link to the corresponding guide in the EKF documentation, where you can find the commands that rok-deploy will perform, as well as troubleshooting sections for any errors that might occur.

Note

If the displayed information doesn’t fit in a single page, a percentage marker will show up in the bottom right corner of the widget. In this case, use the j/k or Page Up/ Page Down keys to navigate the text.

Error Handling

Whenever a verification error occurs, rok-deploy will prompt the user, providing necessary information, like a description of the root cause of the error. For additional context, you can press the Show Logs button, which will show the latest logs that rok-deploy created, before and at the moment that the error occurred. If the error is fatal and the installation can’t proceed, rok-deploy will abort. In this case, you can find the latest logs at /root/.rok/log/deploy.log that exists in your rok-tools management environment.

Input Sources

rok-deploy accepts input from a number of different input sources which form the input hierarchy. Each input source has a specific priority in the hierarchy, meaning that if the rok-deploy can get an input from a higher priority input source, then other lower priority input sources are not taken into account. The hierarchy is the following in descending order:

  1. CLI arguments: You can provide input to rok-deploy directly via CLI arguments. For example, to clone your desired branch, run:

    root@rok-tools:~# rok-deploy --clone-branch <GIT_BRANCH>

    Replace <GIT_BRANCH> with the name of the branch you want to clone, for example:

    root@rok-tools:~# rok-deploy --clone-branch release-2.0

    Note

    For a complete list and description of the supported CLI arguments run:

    root@rok-tools:~# rok-deploy --help
  2. Environment variables: You can export environment variables to give input to rok-deploy. For example, to clone your desired branch, run:

    root@rok-tools:~# export CLONE_BRANCH=<GIT_BRANCH>

    Replace <GIT_BRANCH> with the name of the branch you want to clone, for example:

    root@rok-tools:~# export CLONE_BRANCH=release-2.0

    Note

    You can find the name of the variable associated with an input by running:

    root@rok-tools:~# rok-deploy --help
  3. Preseed file: You can provide a preseed file with inputs by running:

    root@rok-tools:~# rok-deploy --preseed-load <FILE>

    The preseed file is a Python file that declares a SEEDS dictionary that contains key-value pairs of question names and answers, for example:

    SEEDS = { "clone/branch": "release-2.0" }
  4. Environment file: rok-deploy saves its state in environment files under the deploy/ directory in the GitOps repository. Each task has a unique environment file named after its symbolic name, where it will save your choices. You can edit the environment file of a task to change the behavior of rok-deploy.

  5. Frontend: If rok-deploy can’t get input from any of the above sources, then it will prompt you for input.

If you are interested in running rok-deploy non-interactively, make sure to provide input from environment variables, or a preseed file.

See also

How to Launch rok-deploy

To start rok-deploy, in your management environment run:

root@rok-tools:~# rok-deploy

Follow the on-screen instructions to install each deployment task in a consecutive manner.

Summary

In this guide you gained insight into the rok-deploy deployment tasks structure, the information you can get for each deployment task, the input sources that rok-deploy supports, and how you can handle errors using this tool.

What’s Next

Check out the rest of our guides to learn more about EKF features.