🌟Getting started
Last updated
Last updated
You can have a complete development environment to test the API with one click with Gitpod using the following button.
Gitpod is free for 50 hours every month, so you dont have to worry for testing the application.
After a couple of seconds the Gitpod environment will be ready and you will need to start the API, to do this just select "Run and Debug" in the left menu in VS Code and start the application using the "Terrakube" option
After some seconds Terrakube API will be up and running.
Now you can select the "Thunder Client" and open the "Getting Started" collection to test the API
The first step will be to get the authorization token for the Terrakube API.
Execute the request "Get Device Code" and open the URL in field "verification_uri_complete" inside the response to get the authentication token
When you open the "verification__uri__complete" field you should see a similar page.
Authenticate using the user "admin@example.com" with password "admin"
Finally get the access token for the API using the request "Get Access Token"
Now we can start using the API
Terrakube is based on Organization, we can have one or multiple organizations inside Terrakube and we use an organization to save workspaces, jobs, templates, modules, providers and teams.
To create it we will use the request inside the collection "Step 1 - Organization"
Request to create an Organization called "Hashicorp":
We should receive a response like the following:
Now we have the basic element in Terrakube to start testing all the endpoints.
Inside an Organization we can have multiple teams working, each team can have access to different features inside an organization.
To create it we will use the request inside the collection "Step 2 - Teams"
This will create a team called "TERRAKUBE_DEVELOPERS" with access to all the features and you should get a response like the following:
The team name should be a valid "group" name in Azure Active Directory, Google Cloud Identity, Github, Gitlab, OIDC, Amazon Cognito, etc. This will be based on Dex Configuration. For this example we are using Terrakube with a preconfigured LDAP.
This is the basic flow a job inside Terrakube will execute when running a workspace jobs. Templates allows you to define different logic using "Terrakube Configuration Language" using a yaml and small scripts written in Bash or Groovy that can be reused across an organization. To understand better templates lets create some examples:
Templates are sent to the API in base64 encoding.
To create it we will use the request inside the postman collection "Step 3 - Templates"
This is an small template that can be used to run a terraform plan and later run a terraform apply:
Teamplate body:
Request:
Response:
Now we have a template that we can reuse when running jobs across an organization, lets define a couple of more templates.
This is a small template that can be used to destroy the terraform infraestructure.
Template body:
Request:
Response:
Now our firts organization have to templates, one to run a terraform plan/apply and one for a terraform destroy. Lets create a couple of more templates.
Terraform has a lot of open source tools that we can use inside Terrakube using template extensions, Terrakube has an open source repository where extension can be created and share between our community. Lets use some of the available extension to create a template that can calculate the cost of our infrastructure using "Infracost".
Template body:
In this template we are defining a flow where a terraform plan will be executed for the workspace, once the terraform plan is finished Terrakube will import the Infracost extension from the open source repository and calculate the cost.
Request:
Response:
Lets define a new template that use Terrascan open source tool to run a static code analysis of our terraform code.
Template body:
Request:
Response:
This template is importing the Terrascan extension and running a analysis for one particular workspace.
Template 5 - Static Code Analysis Snyk
Lets create a template that is using Snyk open source to run an analysis of our terraform code.
Template body:
Request:
Response:
Now we have the following template available inside our organization:
Terraform Plan/Apply
Terraform Destroy
Terraform Cost with Infracost
Terraform Static Code Analysis with Terrascan
Terraform Static Code Analysis with Snyk
Lets create some workspace where we can use our templates.
For more information about Terrakube extension please refer to the following Github repository. If you want to create a new extension feel free to create an issue and send a pull request. You can even for the repository and create some private extension.
A workspace is a folder inside a git repository where we store our terraform code, we can define all the terraform resources or we can just call a terraform module that is available inside Terrakube modules.
Workspace Git repository can be public or private using the following providers: Github, Gitlab, Azure DevOps, Bitbucket or SSH keys (rsa and ed25519). If you are using a private git respository please refer to the following document.
To create it we will use the request inside the postman collection "Step 4 - workspace"
Lets create a very simple workspace using the following terraform code inside this public git repository "https://github.com/AzBuilder/terrakube-docker-compose.git" using the root folder "/"
You can have multiple workspaces using a single git repository using folders and changing the field "folder" in the request.
Request.
Response.
When a workspace is created inside Terrakube we can define some schedules, this can be useful for example when running cloud infrastructure and we need to create some development environment every day at 8 AM and destroy the environment every day at 5 PM when our IT team stop working.
Request
This schedule will run the workspace using one template every minute
The Terrakube scheduler is based in "Quartz". You can create different schedules for your workspace. Please refer to the following information to define the "cron expression" or you can use the following link to build the expression.
When Terrakube runs a job it will start saving all the states and changes inside the workspace history. To validate all the state changes we can use the workspace history endpoint.
Request
To understand how you can create workspace for any cloud provider please refer to the following examples inside the collection:
Basically to use any terraform provider we just need to define the workspace environment variables.
This is an example of an Azure workspace.
For more information about the workspace please check the api methods for:
After we have a workspace we can start creating jobs for our workspaces using the templates that we have define earlier.
To create it we will use the request inside the postman collection "Step 5 - Jobs"
Request:
After a couple of minutes Terrakube should have completed the job execution
The job output should be similar to the following:
If you wan to check all the available methods you can use the following enpoint.
