Piranha Documentation

Documentation Home

Setup

Most of these demos are written so that you can execute them alongside the relevant cloud provider it is compatible with. It's simple to run identical code against both cloud providers.

For our AWS compatible examples you'll need authentication keys named awsdemo and piranhademo. Add the access keys to your existing ~/.aws/credentials file, or add them to the example provided here AWS Credentials File. If using the example, you'll need to copy it to ~/.aws/credentials

Setup Ansible

Ansible Setup for Linux

  1. Update System Packages Run the following command in bash to update package information: sudo apt update && sudo apt upgrade -y

  2. Install Python Ensure Python is installed (Ansible requires Python). Use: sudo apt install python3 python3-pip -y

  3. Install Ansible and AWS Dependencies Add the official Ansible PPA and install Ansible: sudo apt-add-repository --yes --update ppa:ansible/ansible sudo apt install ansible -y

    Install AWS SDK libraries and community collections: pip3 install boto boto3 ansible-galaxy collection install community.aws

  4. Verify Installation Check the installed Ansible version: ansible --version

  5. Optional Configuration Configure an inventory file to define managed nodes: sudo nano /etc/ansible/hosts

  6. Ansible Official Documentation and Downloads Visit the Ansible Documentation for additional resources. https://docs.ansible.com/

Ansible Setup for Windows

  1. Install WSL (Windows Subsystem for Linux) Open PowerShell as Administrator and run: wsl --install

    Restart the system if prompted.

  2. Install a Linux Distribution From the Microsoft Store, install a Linux distribution (e.g., Ubuntu).

  3. Set Up WSL Environment Launch the installed Linux distribution and complete the initial setup.

  4. Follow Linux Setup Instructions Follow the steps listed above under "Ansible Setup for Linux" within your WSL environment.

  5. Optional: Install Ansible on Windows Directly (using Cygwin) Download and install Cygwin. https://cygwin.com/

    Install Python and Ansible via Cygwin.

  6. Verify Installation in WSL or Cygwin Run the Ansible version command to confirm: ansible --version

  7. Ansible Official Documentation and Downloads Visit the Ansible Documentation for additional resources. https://docs.ansible.com/

Setup AWS CLI

AWS CLI Setup for Linux

Install and Update Requirements

  1. Ensure your system can extract or "unzip" files. If the unzip command is not installed, use an equivalent package manager command to install it.
  2. The AWS CLI requires glibc, groff, and less. These are included by default in most major Linux distributions.
  3. Supported distributions:
    • 64-bit versions of CentOS, Fedora, Ubuntu, Amazon Linux 1, Amazon Linux 2, Amazon Linux 2023, and Linux ARM.
    • Note: AWS does not maintain third-party repositories (except Snap) and cannot guarantee they contain the latest version of the AWS CLI.

Installing AWS CLI

  1. Remove Pre-installed AWS CLI on Amazon Linux (if applicable): sudo yum remove awscli

  2. Command Line Installer (Linux x86 64-bit): curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" unzip awscliv2.zip sudo ./aws/install

  3. Command Line Installer with Custom Directories and Update: curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" unzip awscliv2.zip sudo ./aws/install --bin-dir /usr/local/bin --install-dir /usr/local/aws-cli --update

  4. Snap Package Installation: For automatic updates, install via Snap: sudo snap install aws-cli --classic

    Note: Snap packages do not support selecting specific minor versions.

Verifying AWS CLI Installation

  1. Check the installed version: aws --version

  2. If aws command is not found, verify symbolic links and installation paths: which aws ls -l /usr/local/bin/aws

Verifying Downloaded Files (Optional)

  1. Download the AWS CLI PGP public key: curl -o public-key-file "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip.sig"

  2. Verify the downloaded package: gpg --verify awscliv2.sig awscliv2.zip

  3. Look for a "Good signature" message in the output.

Configuring AWS CLI

  1. Run the configuration wizard: aws configure

  2. Provide the following details: Access Key ID Secret Access Key Default Region (e.g., us-east-1) Output Format (e.g., json)

Reference: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html

AWS CLI Installation Guide for macOS

Prerequisites - Supported macOS versions: 10.15 and later. - AWS CLI may not be up-to-date in third-party repositories; it is recommended to follow the official installation instructions. https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html

Installation Methods You can install or update the AWS CLI using any of the following methods:

  1. GUI Installer Steps: a. Open your browser and download the macOS pkg file: https://awscli.amazonaws.com/AWSCLIV2.pkg b. Run the downloaded .pkg file. c. Follow the on-screen instructions to complete the installation: For all users: - requires sudo access. - You can choose any folder or the recommended default folder: /usr/local/aws-cli. - The installer creates a symlink at /usr/local/bin/aws.

     	For the current user only:
 		- Does not require sudo.
 		- Choose a folder where you have write permission.
 		- After installation, manually create symlinks:
 			$ sudo ln -s /folder/installed/aws-cli/aws /usr/local/bin/aws
 			$ sudo ln -s /folder/installed/aws-cli/aws_completer /usr/local/bin/aws_completer
 d. (Optional) Enable debug logs in the installer:
 	- Press Cmd+L during installation to open the log pane.
 	- The log file is saved to /var/log/install.log.

  2. Command Line Installer (All Users) Steps: a. Download the AWS CLI installation package via command line: $ curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg" b. Install the package using the installer command: $ sudo installer -pkg AWSCLIV2.pkg -target /

  3. Command Line Installer (Current User Only) Steps: a. Download the AWS CLI installation package via command line: $ curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg" b. Install the package locally: $ installer -pkg AWSCLIV2.pkg -target ~/Applications c. Manually create symlinks: $ ln -s /folder/installed/aws-cli/aws ~/bin/aws $ ln -s /folder/installed/aws-cli/aws_completer ~/bin/aws_completer

Post-Installation Verification

  1. Ensure that the AWS CLI is installed and accessible: $ which aws /usr/local/bin/aws

  2. Check the installed version: $ aws --version aws-cli/2.19.1 Python/3.11.6 Darwin/23.3.0 botocore/2.4.5

  3. Restart your terminal if the aws command is not found.

Troubleshooting If you encounter any issues during installation or verification, refer to the Troubleshooting Errors for the AWS CLI. Reference: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-troubleshooting.html

Windows Installation

Requirements - The AWS CLI is supported on Microsoft-supported versions of 64-bit Windows. - Administrative rights to install software are required.

Installation or Update Process

  1. Download the AWS CLI MSI Installer

    • Download the 64-bit MSI installer from the following link: https://awscli.amazonaws.com/AWSCLIV2.msi

  2. Install the AWS CLI Using the Installer a. Run the downloaded .msi file. b. Follow the on-screen instructions to complete the installation process.

  3. Install the AWS CLI Using the Command Line (Optional) You can also install the AWS CLI using the msiexec command for automation or silent installations: a. Standard installation: C:> msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi b. Silent installation (no user prompts): C:> msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi /qn

    For more parameters available with the msiexec command, refer to the Microsoft Docs. https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/msiexec

Verify Installation

  1. Open the Start menu and search for cmd to open the Command Prompt.

  2. Enter the following command to verify the AWS CLI installation: C:> aws --version

    Example output: aws-cli/2.19.1 Python/3.11.6 Windows/10 exe/AMD64 prompt/off

Troubleshooting If the aws command is not recognized, try closing and reopening the Command Prompt to refresh the PATH. Refer to the AWS CLI Troubleshooting Guide for additional help. https://docs.aws.amazon.com/cli/latest/userguide/troubleshooting.html

Setup Terraform

4 Ways to Install Terraform a. Manual installation b. Homebrew on macOS c. Chocolatey on Windows d. Linux

Manual Installation:

  1. Retrieve the terraform binary by downloading a pre-compiled binary or compiling it from source: Pre-compiled binary or Compile from source

    Pre-compiled Binary: To install Terraform, find the appropriate package (https://developer.hashicorp.com/terraform/install) for your system and download it as a zip archive.

     After downloading Terraform, unzip the package. Terraform runs as a single binary named terraform. 
 Any other files in the package can be safely removed and Terraform will still function.

 Finally, make sure that the terraform binary is available on your PATH. This process will differ depending on your operating system.

    Compile from Source: To compile the Terraform binary from source, clone the HashiCorp Terraform repository (https://github.com/hashicorp/terraform) git clone https://github.com/hashicorp/terraform

     Navigate to the new directory.
 	$ cd terraform

 Then, compile the binary. This command will compile the binary and store it in $GOPATH/bin/terraform.
 	$ go install

 Finally, make sure that the terraform binary is available on your PATH. This process will differ depending on your operating system.

  2. Print a colon-separated list of locations in your PATH. $ echo $PATH

  3. Move the Terraform binary to one of the listed locations. This command assumes that the binary is currently in your downloads folder and that your PATH includes /usr/local/bin, but you can customize it if your locations are different. mv ~/Downloads/terraform /usr/local/bin/

Homebrew on macOS Homebrew is a free and open-source package management system for macOS. Install the official Terraform formula from the terminal.

  1. First, install the HashiCorp tap, a repository of all our Homebrew packages. $ brew tap hashicorp/tap

  2. Now, install Terraform with hashicorp/tap/terraform. $ brew install hashicorp/tap/terraform

    Note: This installs a signed binary and is automatically updated with every new official release.

  3. To update to the latest version of Terraform, first update Homebrew. $ brew update

  4. Then, run the upgrade command to download and use the latest Terraform version. $ brew upgrade hashicorp/tap/terraform ==> Upgrading 1 outdated package: hashicorp/tap/terraform 0.15.3 -> 1.0.0 ==> Upgrading hashicorp/tap/terraform 0.15.3 -> 1.0.0

Chocolatey on Windows

  1. Chocolatey is a free and open-source package management system for Windows. Install the Terraform package from the command-line. $ choco install terraform

    Note: Chocolatey and the Terraform package are NOT directly maintained by HashiCorp. The latest version of Terraform is always available by manual installation.

Linux HashiCorp officially maintains and signs packages for the following Linux distributions.

a. Ubuntu/Debian 1. Ensure that your system is up to date and you have installed the gnupg, software-properties-common, and curl packages installed. You will use these packages to verify HashiCorp's GPG signature and install HashiCorp's Debian package repository. sudo apt-get update && sudo apt-get install -y gnupg software-properties-common

2. Install the HashiCorp GPG key (https://apt.releases.hashicorp.com/gpg)
	$ wget -O- https://apt.releases.hashicorp.com/gpg | \
	gpg --dearmor | \
	sudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg > /dev/null
	
3. Verify the key's fingerprint.
	$ gpg --no-default-keyring \
	--keyring /usr/share/keyrings/hashicorp-archive-keyring.gpg \
	--fingerprint
	
4. The gpg command will report the key fingerprint:
	/usr/share/keyrings/hashicorp-archive-keyring.gpg
	-------------------------------------------------
	pub   rsa4096 XXXX-XX-XX [SC]
	AAAA AAAA AAAA AAAA
	uid           [ unknown] HashiCorp Security (HashiCorp Package Signing) <security+packaging@hashicorp.com>
	sub   rsa4096 XXXX-XX-XX [E]

b. CentOS/RHEL 1. Install yum-config-manager to manage your repositories. $ sudo yum install -y yum-utils

2. Use yum-config-manager to add the official HashiCorp Linux repository.
	$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo

3. Install Terraform from the new repository.
	$ sudo yum -y install terraform

c. Fedora 1. Install dnf config-manager to manage your repositories. $ sudo dnf install -y dnf-plugins-core

2. Use dnf config-manager to add the official HashiCorp Linux repository.
	$ sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo
	
3. Install Terraform from the new repository.
	$ sudo dnf -y install terraform

d. Amazon Linux 1. Install yum-config-manager to manage your repositories. $ sudo yum install -y yum-utils

2. Use yum-config-manager to add the official HashiCorp Linux repository.
	$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo
	
3. Install Terraform from the new repository.
	$ sudo yum -y install terraform

Verify the installation 1. Verify that the installation worked by opening a new terminal session and listing Terraform's available subcommands. $ terraform -help Usage: terraform [-version] [-help] [args]

	The available commands for execution are listed below.
	The most common, useful commands are shown first, followed by
	less common or more advanced commands. If you're just getting
	started with Terraform, stick with the common commands. For the
	other commands, please read the help and docs before usage.
	##...
2. Add any subcommand to terraform -help to learn more about what it does and available options.
	$ terraform -help plan

Troubleshoot If you get an error that terraform could not be found, your PATH environment variable was not set up properly. Please go back and ensure that your PATH variable contains the directory where Terraform was installed.

Enable tab completion If you use either Bash or Zsh, you can enable tab completion for Terraform commands. To enable autocomplete, first ensure that a config file exists for your chosen shell.

For Bash
	$ touch ~/.bashrc

	Then install the autocomplete package.
		$ terraform -install-autocomplete
	
For Zsh
	$ touch ~/.zshrc
	
	Then install the autocomplete package.
		$ terraform -install-autocomplete

Once the autocomplete support is installed, you will need to restart your shell.

Setup Git

Setting Up Git

Prerequisites Before installing Git, ensure the following: - You have administrative rights on your system. - Internet access to download the necessary files.

Git can be installed on the following operating systems: - Windows - macOS - Linux

Installation and Configuration For Windows

  1. Download Git Installer Visit the Git official website (https://git-scm.com/) and download the latest version of Git for Windows.

  2. Run the Installer Locate the downloaded .exe file and double-click it to run the installer.

  3. Follow the Setup Wizard a. Select the components to install. Leave the defaults unless you have specific needs b. Choose a text editor to use with Git (default is Vim; you can choose others like Visual Studio Code or Notepad++). c. Adjust your PATH environment variable. The recommended setting is “Git from the command line and also from 3rd-party software.” d. Configure line ending conversions. Choose the option most appropriate for your use case: - “Checkout Windows-style, commit Unix-style line endings” is recommended for most users.

  4. Complete Installation Finish the wizard and verify installation by opening the command prompt and running: git --version

For macOS Option 1: Using Homebrew 1. Install Homebrew If Homebrew is not installed, run: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Git
Use Homebrew to install Git:
	brew install git

3. Verify Installation
Open a terminal and run:
	git --version

Option 2: Direct Download 1. Download Git Installer Download the latest macOS Git installer from git-scm.com.

2. Run the Installer
Follow the on-screen instructions to complete the installation.

3. Verify Installation
Open a terminal and run:	
	git --version

For Linux

  1. Update Package Index Run the following command to ensure your package manager is up-to-date: sudo apt update # For Debian/Ubuntu sudo yum update # For CentOS/RHEL

  2. Install Git Use the appropriate command for your distribution: sudo apt install git # For Debian/Ubuntu sudo yum install git # For CentOS/RHEL

  3. Verify Installation Run: git --version

Initial Git Configuration After installation, configure Git with your user details and preferences.

  1. Set Your Identity Run the following commands to configure your username and email: git config --global user.name "Your Name" git config --global user.email "youremail@example.com"

  2. Set Default Editor To set your preferred text editor: git config --global core.editor "editor-name"

    Replace editor-name with your preferred editor, e.g., vim, nano, or code for Visual Studio Code.

  3. Enable Useful Aliases Add common aliases for convenience: git config --global alias.st status git config --global alias.co checkout git config --global alias.br branch git config --global alias.cm commit

  4. Verify Configuration To view your Git configuration, run: git config --list

For our Github compatible examples, you'll need an SSH Key or other authentication method to push code to the SCM repository.

Instructions

Each of the demos includes its own Readme file with further

Structure