alnoda-workspaces/workspaces/ansible-terraform-workspace/docs/getting-started.md

Getting started

Quicklaunch

From the quicklaunch page you can open workspace tools, such as code editor or terminal

Demo: Quicklaunch

Code Editor

Code editor of this workspace is Eclipse Theia - an open-source version of popular Visual Studio Code IDE. despite Eclipse Theia is a browser-based code editor, it is fast, responsive, and full-featured. It features code highlighting, autocompletion, rendering of notebooks has a tree-based file browser, and a great number of pre-installed color themes.

Demo: Eclipse Theia

You can install any extension from open-vsx.org that has hundreeds of extensions for VS Code compatible editors. The IDE is already configured to make code highlighting for a great number of programming languages and file types. It also has many popular extensions installed

Terminal

Workspace has full-size browser-base terminal

Use workspace workspace terminal to install new applications. Install with sudo apt install. The default abc user is allowed to install packages.

For example, in order to install Emacs text editor open workspace terminal, and execute

sudo apt-get update
sudo apt install emacs

Ansible

Workspace includes example ansible playbook - a simple play that installs packages in localhosts

cd /home/examples/ansible-local && ansible-playbook install-packages.yml

Ansible Ara

ARA Records Ansible and makes it easier to understand and troubleshoot. Ansible Ara is fully configured in the Ansible-Terraform workspace - it captures any execution (manual or scheduled) of any ansible playbook.

Ara server is up and running in the workspace, and available on the internal port 8029. If you mapped standard ports to your Ansible-Terraform workspcae, then Ansible Ara WEB UI is on localhost:8029

Ansible report

Ansible-report is a small utility that generates several reports from your ansible project - visualizes inventory, represents all plays in a format of graphs, generates interactive static website with information about hosts etc.

cd /home/examples/ansible-local && ansible-report

Ansible-report is a shell script that simply executes several ansible tools in one shot:

• ansible-lint
• ansible-cmdb
• ansible-inventory-grapher
• ansible-playbook-grapher (for all ansible plays in the folder)

You can also use any of the ansible tools separately.

Ansible Lint

Ansible Lint is a command-line tool for linting playbooks, roles and collections aimed towards any Ansible users. Cd to the folder with your Ansible project and execute

ansible-lint --nocolor > /home/static-server/ansible-lint.txt

Ansible-cmdb

Ansible-cmdb takes the output of Ansible's fact gathering and converts it into a static HTML overview page (and other things) containing system configuration information. Cd to the folder with your Ansible project and execute

ansible -m setup --tree out/ all
ansible-cmdb out/ > overview.html

Ansible inventory grapher

Ansible-inventory-grapher creates a dot file suitable for use by graphviz. Cd to the folder with your Ansible project and execute

ansible-inventory-grapher all | dot -Tpng > /home/static-server/my.png

Ansible Playbook Grapher

Command line tool to create a graph representing your Ansible playbook plays, tasks and roles. The aim of this project is to have an overview of your playbook. Cd to the folder with your Ansible project and execute

ansible-playbook-grapher --include-role-tasks example.yml -o /home/static-server/example

Ansible Doctor

Ansible-doctor is a simple annotation like documentation generator based on Jinja2 templates. while ansible-doctor comes with a default template called readme, it is also possible to write your own templates.

The first step is to identify if the given folder is an Ansible role. This check is very simple, if the folder contains a sub-directory called tasks is MUST be an Ansible role! :)

After the successful check, ansible-doctor will try to read some static files into a dictionary:

• defaults/main.yml
• meta/main.yml

Cd to the folder with your Ansible project and execute

ansible-doctor -o /home/static-server/ roles/example_production

Schedule Ansible playbook executions

Ansible-Terraform workspace has 2 tools (Cronicle and ARA) that make it simple and convenient to use Ansible for periodic tasks and jobs. For example, maintenance jobs for your cloud infrastructure. This is especially handy if you run this workspace on a remote server.

• [Cronicle] - allows to schedule tasks and jobs, and lets you observe executions using a nice UI
• [Ansible Ara] - tracks all executions of ansible playbooks (manual or scheduled), and has nice UI that provides informationn about every step of every playbook execution

You can try scheduling an example ansible playbook with Cronicle

NOTE: Scheduling Ansible playbooks is especially useful if you launch Workspace on a remote server rather than on your local laptop.

Terraform

Terraform is an open-source infrastructure as code software tool that provides a consistent CLI workflow to manage hundreds of cloud services. Terraform codifies cloud APIs into declarative configuration files.

Ansible-Terraform workspace contains a small example Terraform project that creates a server on the Scaleway cloud

cd /home/examples/terraform-scaleway/ && terraform init

Set Scaleway credentials as environment variable in your workspace. Add the following lines to /home/abc/.zshrc:

export SCW_DEFAULT_PROJECT_ID=<YOUR_PROJECT_ID>
export SCW_ACCESS_KEY=<YOUR_ACCESS_KEY>
export SCW_SECRET_KEY=<YOUR_SECRET_KEY>

Restart terminal, and execute

cd /home/examples/terraform-scaleway/ && terraform plan

Create infrastructure with

cd /home/examples/terraform-scaleway/ && terraform apply

Terraform report

A small tool that produces several outputs from a terraform project and visualizes terraform plan as an interactive HTML page.
Terraform report can be generated from the small example terraform project, included in the Workspace

cd /home/examples/terraform-scaleway/ && terraform-report

Terraform-report outputs artefacts to the folder /home/static-server/terraform-reports/. This folder is served by the Static File Server that you can use to view the artifacts, that include interactive HTML pages

Example with AWS

If you want to try Terraform report with your own AWS account, open workspace and configure AWS profile - create file with AWS credentials

mkdir -p ~/.aws
nano ~/.aws/credentials

The file ~/.aws/credentials would look like this

[terraform]
aws_access_key_id = <YOUR_AWS_KEY>
aws_secret_access_key = <YOUR_AWS_SECRET>

Clone your terraform project to the workspace, or if you don't have any, you can use this terraform example repository:

git clone https://github.com/pvarentsov/terraform-aws-free-tier /home/project/aws-example

Open file /home/project/aws-example/src/free-tier/main.tf and comment out the part that configures S3 backend

terraform {
  backend "s3" {}
}

Initialize a working Terraform directory

cd /home/project/aws-example/src/free-tier && terraform init

Paste public ssh key (for the sake of example you can type anything)

nano ./provision/access/free-tier-ec2-key.pub

Now you can generate terraform report

terraform-report

Use Static File Server to review the report

Terraform Rover

Rover - is an awesome Terraform visualizer with browser-based UI. Rover helps to better understand Terraform state and planned changes. To see how Rover works, you can use a basic Terraform example in folder /home/examples/terraform-scaleway/. Initialize Terraform project first

cd /home/examples/terraform-scaleway/ && terraform init

and start Rover to visualize terraform state

rover --workingDir /home/examples/terraform-scaleway/

If you have followed hands-on the tutorial from the previous section (terraform report from the terraform-aws-free-tier repo), you can visualize it with Rover:

rover --workingDir /home/project/aws-example/src/free-tier

Blast Radius

Blast Radius is a tool for reasoning about Terraform dependency graphs with interactive visualizations. You can try Blast Radius - launch workspace and visualize an example Terraform project.

cd /home/examples/terraform-scaleway && terraform init
blast-radius --serve --port 8030

open localhost:8030 in browser

NOTE: Blast Radius is a great project, but there is lack of updates to the project recently, and it might not work with some Terraform providers.

Terraform pre-commit hook

Pre-commit git hooks to take care of Terraform configurations. Workspace has all dependencies installed.

Terraform Inframap

• Visualize terraform state

inframap generate terraform.tfstate | dot -Tpng > graph.png