CACAO Terraform templates on the CLI¶
This tutorial will guide you through the process importing a basic terraform template into CACAO.
A more detailed version of this tutorial can be found here https://docs.jetstream-cloud.org/ui/cacao/import_terraform_template/
By the end of this tutorial, you will have imported a terraform template into CACAO and deployed it using the UI to confirm that it works.
- Basic understanding of Terraform, git, and the command line.
- An OpenStack environment with access to the API (if you need to validate any terraform changes).
- Terraform installed on your local machine or VM server (if you need to validate any terraform changes).
- An SSH key pair to access the VM server running Terraform (if you need to validate any terraform changes).
CyVerse CACAO Browser UI¶
One of CyVerse's test deployments for CACAO will be used for this exercise so that we can import a template using the newer metadata schemas, which will be deployed to production in the very near future.
The url for the CACAO site that we will use today is https://cacao.jetstream-cloud.org
Please login to verify that your ACCESS credentials work with the CACAO test site. !!!+ warn For the workshop, use the "ACCESS CI (XSEDE)" identity provider when you login.
Installation of the CyVerse CACAO CLI¶
If you are using a VM provided by the workshop, the CACAO CLI is already installed. You can skip this installation section.
The CyVerse CACAO CLI is a command line tool interact with the CyVerse CACAO API. The first step is the install the cli on your local machine or to a vm.
- Linux download for CACAO CLI
- Windows download for CACAO CLI
- MacOS (Intel) download for CACAO CLI
- MacOS (ARM) download for CACAO CLI
If you're using a VM provided by the workshop or a Linux system, you can use these instructions to install the CACAO CLI.
- If necessary, obtain a shell or terminal on the Linux system you wish to install the CACAO CLI.
- Copy link for "Linux download for CACAO CLI" from above.
curl https://gitlab.com/cyverse/cacao/-/package_files/88735155/download --output cacao.zip
unzip cacao.zip # this will create a file cacao_linux_amd64
sudo mv cacao_linux_amd64 /usr/local/bin/cacao # optional; otherwise, add it into your path
chmod +x /usr/local/bin/cacao
Reviewing the Terraform template we will use to import¶
We will be using https://github.com/cyverse/cacao-terraform-hello-world for this tutorial.
You will find a directory called
.cacao at the root of the template and two files:
metadata.json, which contains the CACAO-specific metadata for the template
ui.json, which contains the UI-specific hints for the template
ui.json file is optional, and if not present, then the CACAO UI will present a default naive rendering of the template.
Details about the metadata and ui schemas can be found here: https://docs.jetstream-cloud.org/ui/cacao/import_terraform_template/
The UI metadata specification is currently in flux and will likely change in the near future, especially as we get feedback from the community.
Stop! If you want to fork the template, let's do it now.¶
!!!+ info This is an optional step. You do not need to fork a template for this part of the tutorial, but you may if you wish.
Using the CACAO CLI¶
Login to CACAO CLI¶
cacao login --browser
What to do if you encounter a login issue
Sometimes login using the command line will fail -- a typo happens, a copy-n-paste of a token happens, using the wrong api url happens, etc -- and you need to reset your login. To reset your login, you can use the following command:
- Enter the CACAO API url:
- In your browser open the following URL (this is also echoed in the terminal, line #5): https://cacao.jetstream-cloud.org/api/user/login !!!+ warn For the workshop, use the "ACCESS CI (XSEDE)" identity provider when you login.
- You will need to grab the the "access_token" that is returned from the browser and paste the following text into the terminal: "Bearer" followed by a space and then the access token. For example, if the access_token were GOOSE, the the string you enter will be:
- Do not include the quotes around the token.
Beareris case sensitive.
- There is one space between Bearer and the token.
Below are screenshots of what you might expect to see from Chrome and Firefox.
After pasting the "Bearer " + access_token, you should return to the shell prompt.
- To test a successful login, you can execute a cacao command, such as:
cacao provider get
Importing a Terraform template into CACAO¶
cacao template create git <source url> <template name> --branch <git branch> --path <path to template>
Here are the values to enter for each:
<template name>: "
-hello-world" (e.g. student0001-hello-world)
<path to template>:
!!!+ warn If you forked the template, you will need to use your forked url.
Putting this all together, your command will look similar to this:
tid value for later use.
Launching a template using the CACAO UI¶
- Open the CACAO UI in your browser: https://cacao.jetstream-cloud.org
- Click on the "Deployments" tab on the left-hand side.
- Click on the "+ Add Deployment" button.
- Select the "edwin's hello world example"/"student0001-hello-world" template. (Note: the subname of the template will be different for you.)
- Click the "Next" button.
- Fill out the Parameters
Choose Region: leave as default
Instance name: enter your student name (e.g. student0001) + date e.g.
Image: select "Featured-Ubuntu22"
Size: leave as default
- Click the "Next" button.
- After reviewing the summary, click the "Submit" button.
- You will be listed on the "Deployments" page. You can click on the deployment to see the status of the deployment.
While you are waiting, questions or we can begin the next section, "What if you want to customize a template?"
Cleaning up (if you didn't fork your template)¶
You will not be able to delete a template if there are any active deployments using it.
1. Delete the deployment in the UI or cli (
cacao deployment delete <deployment id).
cacao template delete <template id>
What if you make changes to a template and want to use it for new deployments?¶
Answer: You do not need to do anything. The CACAO UI will automatically detect changes to the template on the configure branch and will use the latest branch code new deployments.
What if you make metadata changes to a template (e.g.
.cacao/ui.json) and want to use it for new deployments?¶
cacao template sync <tid>
For those of you who forked the repo, we can experiment with template modifications¶
Here are a couple suggestions * change the name of the template * remove image (and/or size) from the template and set it
What if you want to customize a template you don't own but is public?¶
If there is time, we can go through this section. Otherwise, you can try this on your own.
- Fork the template into your own github or gitlab account
- Add a
.cacao/ui.jsonto your forked template
- Import the template using the
cacao template create gitcommand.