Documentation

Guidelines

Login #

 👤User  👥Manager  🤝Partner

Create your password #

Upon registration you will receive a notification in your mailbox. Open the link from e-mail to create a new password.

🔥
Warning

Remember: Password should contain at least 1 uppercase, 1 lowercase, 1 number, 1 non alphanumeric and minimum length is 6 signs.

After you fill in your e-mail and new password, you will see the Taikun login page.

visit reset password login

Login #

Go to Taikun.cloud and press the Go to Taikun button. You will see your Dashboard right after signing in.

log in

Forgotten Password #

If you insert a wrong password, you’ll get alerted with a Bad credentials error message. Use the Forgot your password? button which will help you to restore your credentials.

forgotten password

You will receive a new notification in your mailbox – use it to restore your password.

mail forgotten password

Change e-mail address or password #

 👤User  👥Manager  🤝Partner

Change E-mail #

🔥
Warning

You can change your e-mail only if your mail is verified (confirmed).

If you want to change your address for login or email notifications, use the Change E-mail button within your profile settings, insert a new e-mail address, and hit Update. Your new address is now added. Keep in mind it needs to be confirmed!

change mail

Change password #

Use the Change Password button and create a new password.

🔥
Warning

You will be logged out after clicking the Update button. Now, you can sign in with a new password.

change password

For more information, see:

Add Cloud Credentials #

👥Manager  🤝Partner

If you are struggling with adding the Clouds, check our Where to find credentials guide.

You’ll find examples for every available Cloud below.

Openstack #

Requirements for Openstack #

🔥
Warning

A Taikun image must already exist in the Openstack Cloud. Requirement is an Ubuntu 20 image, we recommend using the most recent kernel (e.g. a base Ubuntu image with hwe kernel available here: https://repo.itera.io/repository/images/taikun-image.qcow2)

To use an image in Taikun you have to use the tags “taikun” and “ubuntu{number}”. By default Taikun takes an image with the latest {number}.

Command to add an image to Openstack:

openstack image create –disk-format qcow2 –container-format bare –public –tag taikun –tag ubuntu20.04 –property hw_disk_bus=scsi –property hw_scsi_model=virtio-scsi taikun-focal-image –file taikun-image.qcow2

Adding your Openstack Cloud credentials:

add cc openstack
  1. Switch to Cloud credentials in Taikun 

  2. Hit Add Cloud Credentials in the top-right corner

  3. Specify the following parameters in the Openstack section:

    • Cloud Name – choose name for your Cloud Credentials (3-30 characters, e.g. cloud-test)
    • User – your user name to OpenStack (e.g. user)
    • Password – your password to OpenStack (e.g. 123abc)
    • URL – Endpoint-Identity (e.g. https://cloud.mycloud.com:32132)
    • Domain – insert domain name (e.g. default)
    • Project – select Project if there are multiple options (e.g. my-cloud-project)
    • Region – select Region if there are multiple options (e.g. RegionOne)
    • Public Network – choose network, if available (e.g. public2)

    • Optional:
      • Specify Availability Zone
      • Volume Types 
      • Enable Import Network
🔥
Warning

If you choose to import your network, DNS created in Access Profiles will be ignored.

Enable Import Network
🔥
Warning

If entered Credentials are invalid, you will be notified that Cloud cannot be connected.

Adding your Amazon Web Services (AWS) Cloud credentials #

add cc aws
  1. Switch to Cloud credentials in Taikun 

  2. Hit Add Cloud Credentials in the top-right corner

  3. Specify the necessary parameters in the Amazon Web Services section:

    • Cloud Name – choose name for your Cloud Credentials (3-30 characters, e.g. cloud-test)
    • Access Key ID, Secret Access Key – input your AWS credentials (My Security Credentials will help you finding it)
    • Region – choose suitable region
    • Availability Zone – choose availability for a region 

Azure #

Before adding the Azure account, you need to create an application registration with commands. (source)

ℹ️
Info

The provided instructions are specific to Linux. It might look different with another Operating System.

1) If you haven’t installed Azure CLI, you can do it with the following command:

sudo apt install azure-cli -y

2) Login

sudo apt-get install azure-cli

You will be redirected to an Azure page where you can choose your account:

Web login

CLI output will be similar to this: 

[
  {
    "cloudName": "AzureCloud",
    "id": "c0xxxxa5-xxx-4ecb-xxxx-f37bxxxx28d6",
    "isDefault": true,
    "name": "Bezplatná zkušební verze",
    "state": "Enabled",
    "tenantId": "32xxxxb3-xxx-46b3-xxxx-0exxxxc46d1",
    "user": {
      "name": "usermail@gmail.com",
      "type": "user"
    }
  }
]

You’ll need to fetch Azure Subscription ID (“id”) and Azure Tenant ID (“tenantID”) fields from the output. Here’s what we would use in our test instance:

"id": "c0xxxxa5-xxx-4ecb-xxxx-f37bxxxx28d6”

"tenantId": "32xxxxb3-xxx-46b3-xxxx-0exxxxc46d1"

3) Create a new Azure App with the following command: 

az ad app create --display-name kubernetes --identifier-uris http://kubernetes --homepage http://example.com --password CLIENT_SECRET

You’ll need to use your Client Secret in this command which can be deleted later (e.g. “Ue9)Qj^V\~UYES3(C”)

CLI output will look like this: 

{
  "acceptMappedClaims": null,
  "addIns": [],
  "allowGuestsSignIn": null,
  "allowPassthroughUsers": null,
! "appId": "7bxxxxc3-xxxx-4d74-xxxx-8c40xxxb558", !
  "appLogoUrl": null,
  "appPermissions": null,
  "appRoles": [],
  "applicationTemplateId": null,
  "availableToOtherTenants": false,
  "deletionTimestamp": null,
  "displayName": "kubernetes",
  "errorUrl": null,
  "groupMembershipClaims": null,
  "homepage": "http://example.com",
  "identifierUris": [
    "http://kubernetes"
  ],
  }
  ...
  {
    "adminConsentDescription": "Allow the application to access kubernetes on behalf of the signed-in user.",
    "adminConsentDisplayName": "Access kubernetes",
    "id": "59xxx87-xxxx-47b8-xxxx-1708xxxxefcd",
    "isEnabled": true,
    "type": "User",
    "userConsentDescription": "Allow the application to access kubernetes on your behalf.",
    "userConsentDisplayName": "Access kubernetes",
    "value": "user*impersonation"
  }
...
}

You’ll need to use the “appID” parameter from this output. In our example, it would be:


"appId": "7bxxxxc3-xxxx-4d74-xxxx-8c40xxxb558"

4) Create service principal for the app:

az ad sp create --id appId

Use “appId” from the previous step here: 

az ad sp create -id 7bxxxxc3-xxxx-4d74-xxxx-8c40xxxb558

CLI output example:

{
  "accountEnabled": true,
  ...
}
...
"objectId": "85xxxxcb-xxxx-4761-xxxx-63fxxxx515e",
  "objectType": "ServicePrincipal",
  "odata.metadata": "https://graph.windows.net/32xxxxb3-xxxx-46b3-xxxx-0e33xxxx46d1/$metadata#directoryObjects/@Element",
  "odata.type": "Microsoft.DirectoryServices.ServicePrincipal",
}
...

5) Create a role assignment:

az role assignment create --role "Owner" --assignee http://kubernetes --subscription SUBSCRIPTION_ID

In this case, you will use the subscription ID from the step №2:

az role assignment create --role "Owner" --assignee http://kubernetes --subscription c0xxxxa5-xxx-4ecb-xxxx-f37bxxxx28d6

You’ll find the following CLI output:

{
  "canDelegate": null,
  "id": "/subscriptions/c0xxxxa5-xxx-4ecb-xxxx-f37bxxxx28d6/providers/Microsoft.Authorization/roleAssignments/4fxxxx7f-xxxx-4ccf-xxxx-7287xxxxfa14",
  "name": "4fxxxx7f-xxxx-4ccf-xxxx-7287xxxxfa14",
  "principalId": "85xxxxcb-xxxx-4761-xxxx-63ffxxxx515e",
  "principalType": "ServicePrincipal",
  "roleDefinitionId": "/subscriptions/c0xxxxa5-xxx-4ecb-xxxx-f37bxxxx28d6/providers/Microsoft.Authorization/roleDefinitions/8exxxx57-xxxx-443c-xxxx-2fe8xxxxb635",
  "scope": "/subscriptions/c0xxxxa5-xxx-4ecb-xxxx-f37bxxxx28d6",
  "type": "Microsoft.Authorization/roleAssignments"
}

Now you have all needed Azure IDs! You can also locate them in your Azure portal.

Please be careful when inserting the credentials. If you add incorrect credentials, you will not be able to add flavor and then create cluster.

You can switch to Taikun and add your Azure credentials now:

add cc azure 1
  1. Switch to Cloud credentials in Taikun
     
  2. Hit Add Cloud Credentials in the top-right corner
  3. Specify the necessary parameters in the Azure section:

  • Cloud Name – choose name for your Cloud Credentials (3-30 characters, e.g. cloud-test)
  • Azure Client ID
  • Azure Client Secret
  • Azure Tenant ID

Where to find credentials #

Openstack #

As you should know your username and password, the other data from Openstack will be added to Taikun automatically after filling the URL.

To find the URL:  

  1. Log into your Openstack account 
  2. Locate the Project – API Access section in the left-hand navigation panel
  3. Find the Identity row and copy its Service Endpoint 
openstack url

Amazon Web Services (AWS) #

  1. Log into your AWS account
  2. Click on your profile name in the top-right corner and access Security credentials section
aws 1
  1. Here you can create a new Access key along with a Secret key in the Access key ID and secret access section
    • Alternatively, you can use your previous combination (as long as you have your Secret key)
aws 2

Additional AWS documentation

Azure #

If you haven’t created your application via CLI, you can find the guidelines here.

Credentials for Azure are located in different tabs. Instructions on where to find them are posted below.

Please be careful when inserting the credentials. If you add incorrect credentials, you will not be able to add flavor and then create cluster.

Azure Client and Tenant Id
  • Azure Active Directory – App registrations – All Applications – application -> Application (client) ID (=Azure Client Id) and Directory (tenant) ID (Azure Tenant Id)
azure client tenant id 1
azure client tenant id 2
  • Azure Active Directory – App registrations – All Applications – application – Certificates & secrets – Client secrets -> Value (=Azure Secret Id)
azure client secret 1
azure client secret 2
azure client secret 3
azure client secret 4
🔥
Warning

Client Secret is shown only for the first time, we recommend to save it somewhere else.

Azure Subscription Id
ℹ️
Info

Subscription is chosen from drop-down selection, but you can find below where to find your Subscription ID.

  • Subscriptions -> Subscription ID (=Azure Subscription Id)
azure subscription 1
azure subscription 2

More information is provided in the Azure guideline

Creating Profiles #

 ?Manager  ?Partner

If you want to use one of these profiles in your project, you have to add them first, then select them from selection during project creation.

🔥
Warning

Keep in mind you have to add profiles (kubernetes, access and standalone profiles) during project creation otherwise you cannot do it later..

Kubernetes Profiles #

Set parameters for your kubernetes profile and choose it from drop-down selection during project creation.

add kubernetes profile
Figure.1: Kubernetes profiles

Access Profiles #

Set parameters for your access profile and choose it from drop-down selection during project creation.

add access profile
Figure.2: Access profiles

Alerting Profiles #

ℹ️
Info

Alerting profile can be attached after project is created

Set parameters for your alerting profile and choose it from drop-down selection during project creation.

add alerting profile
Figure.3: Aletring profiles

Policy Profiles #

ℹ️
Info

Policy profile can be attached after project is created

Set parameters for your policy profile and choose it from drop-down selection during project creation.

add policy profile
Figure.4: Policy profiles

Standalone Profiles #

Set parameters for your standalone profile and choose it from drop-down selection during project creation.

add standalone profile
Figure.5: Standalone profiles

Creating a Cluster #

 ?Manager ?Partner

If you have connected your cloud, you can create a new project.

1) Manager/Partner has to create a new project and assign it to a user.

create project assign user
Figure.1: Add project and assign it to user
🔥
Warning

Keep in mind you have to add profiles during project creation otherwise you cannot do it later.

2) Manager/Partner binds flavors needed to the new project.

a) during project creation

add flavor during creation
Figure.2: Flavor – project creation

b) in Flavor Info

add flavor flavor info
Figure.3: Flavor – Flavor info
?
Warning

For a well-functioning cluster you should NOT use small flavors.

3) Now User/Manager/Partner can create new servers in the project. Keep in mind, that a working cluster consists at least of 1 Bastion, 1 Kubemaster and 1 Kubeworker. However, you can also create a multimaster by creating more than 1 Kubemaster, the number of masters must be odd. If you want to create a multimaster, you have to do it before commit.

ℹ️
Info

  • bastion recommended 2 vCPU + 2GB of RAM
  • masters recommended 4 vCPU + 8GB of RAM

add workers
Figure.4: Add servers
  • use shortcuts:
    • b – bastion
    • m – master
    • w – worker
    • numbers of master/worker for faster server addition
ℹ️
Info

The bigger flavor you choose the longer it will take to create.

  • commit
?
Warning

Control if you have all servers you need, the creation can take some time (approx. 7 min per server).

User: Also double check if you need all of them because later you won’t be able to delete them.

commit
Figure.5: Commit
  • creating the project, servers get through the stages:
    • pending➡updating➡ready
  • successful creation, the project is Ready
servers ready
Figure.6: Ready
  • failed creation, the project is Failed or Pending without any action
    • if servers fail during creation, best way to restore them is with repair button (details: UserManagerPartner)
  • delete servers
    • Manager/Partner can delete unnecessary servers
delete server
Figure.7: Delete unnecessary servers
ℹ️
Info

You can delete servers to still have working cluster (1 bastion, 1 master and 1 worker) or delete the whole working cluster.

4) Control remotely.

Use kubeconfig file to connect to your kubernetes.

?
Warning

Please do NOT deploy any apps in monitoring Service, because Taikun uses the monitoring namespace heavily! And if you disable the monitoring, all PVC’s in monitoring will be deleted.

Kubeconfigs, Backup, Monitoring, Lock, Reboot #

User  ?Manager  ?Partner

Kubeconfigs #

Create and download kuberenetes configuration to organize information about clusters, users, namespaces, and authentication mechanisms.

kubeconfig
Figure.1: Kubeconfig
ℹ️
Info

Manager/Partner: You can see and delete other user’s kube configs, but you cannot use them for connecting, if the kubeconfig is not for everyone. User: You can use and delete only your kube config.

See info for UserManager and Partner.

?
Warning

The following features are only for Manager and Partner.

Enable/Disable Backup #

1) If you want to have a backup, first you must add Backup credentials:

add backup credentials
Figure.2: Add backup credentials

Fill all fields for S3 credentials and add connect them with add button.

backup credentials
Figure.3: Backup credentials overview

2) Enable backup.

a) You can enable backup during creation.

enable backup project creation
Figure.4: Enable backup

b) Backup can be enabled also after the project is created.

First you have to enable back and then choose credentials.

enable backup after project creation
Figure.5: Backup after project creation

4) After you enabled backup, you must set up backup policy

add backup policy
Figure.6: Backup policy
?
Warning

Once the policy is add, the cronjob starts.

More info for Manager and Partner.

5) To terminate the backup, delete the policy.

6) If you no longer want to use back, disable it

Enable/Disable Monitoring #

1) Enable monitoring during creation of the project.

enable monitoring project creation
Figure.7: Enable monitoring during project creation

2) Or you can enable monitoring after you create the project.

enable monitoring after project creation
Figure.8: Enable monitoring after project creation

The process takes up to 2 minutes and if successful, Logs, Alerts and Metrics are enabled.

3) Disable Monitoring the same way.

Lock/Unlock #

If Manager/Partner lock the project, you can only preview some pages but you can’t make any changes (actions).

lock project
Figure.9: Locked project

You can see if the project islock unlock orunlock locked in project info:

lock project info
Figure.10: Lock – project info

or in Project overview – Actions section:

lock actions
Figure.11: Lock – project overview

Reboot #

You can reboot servers directly from Taikun.

For Openstack you can choose HARD or SOFT reboot for each server.

For AWS and Azure there is only simple reboot available.

reboot
Figure.12: Reboot

For more info see:

 

Terraform Provider for Taikun Workshop #

User  ?Manager  ?Partner

Introduction #

The purpose of this workshop is to introduce you to Terraform and the Terraform Provider for Taikun. The latter will allow you to use Terraform to manage resources in Taikun.

Annotations #

  • Text in this form is to be typed, as is, on the command line.
cd workshop/
ls
echo Hello!
  • This form of text shows screen output, usually the output of commands.
task_00/
task_01/
...
Hello!
  • This format is for code in Terraform’s configuration language, HashiCorp Configuration Language (HCL).
resource "aws_instance" "example" {
  ami = "abc123"

  network_interface {
    ...
  }
}
  • You may wish to skip reading information blocks if you are already familiar with Terraform and its configu- ration syntax.
ℹ️
Info

Some information about Terraform…

Setup #

To complete this workshop, you will need to install Terraform and the workshop files. There are two ways to do this. – If you wish to install Terraform and the workshop files locally, read Local setup. – To use the provided Docker image which already contains everything you need.

Setup using Docker. #

Local setup
REQUIREMENTS
  • You must have Terraform version 0.14 or newer installed.
  • You will need Git to clone the provider’s repo.
INSTALLING TERRAFORM

This Hashicorp tutorial explains how to install Terraform on OS X, Windows and Linux.

DOWNLOADING THE WORKSHOP FILES

Clone the workshop directory and switch into the workshop/ directory.

git clone https://github.com/itera-io/terraform-provider-taikun-workshop.git
cd terraform-provider-taikun-workshop/workshop/
Setup using Docker
REQUIREMENTS

You must have Docker and Git installed.

SETUP

Start by cloning the workshop repository.

git clone --recursive https://github.com/itera-io/terraform-provider-taikun-workshop.git

Docker image creation #

You’ll need to build the image, this operation can take several minutes.

DOCKER_BUILDKIT=1 docker build --rm --target bin -t tf-workshop .

Docker container creation #

To create the Docker container, run one of the following commands from the root of terrraform-provider-taikun-workshop.

  • On Windows, run the following command in the command prompt (not Powershell).
docker run -v %CD%/workshop:/root/workshop --name tf-workshop -it tf-workshop

• On Linux and MacOS:

docker run -v $(pwd)/workshop:/root/workshop --name tf-workshop -it tf-workshop

This will mount the workshop/directory in the Docker container and log you in to the container as root. In other words, you will need to run terraform commands from within the container shell, however you can edit the files in workshop/directory with the editor of your choice on your machine.

Restarting the Docker container

You can exit the container at any time without losing your progress. If you have exited the Docker container, run the following command to restart it.

docker start -i tf-workshop
Text editing within the container

If you wish to edit the files in workshop/directory from within the container, the Docker image has the vim, micro and nano packages installed. If you are unfamiliar with Nano and Vim keybindings, the Micro editor has traditional Common User Access keybindings (Ctrl-C for copy, Ctrl-Z for undo, etc).

Documentation #

The provider documentation is available on the Terraform Registry.

Tasks #

The end goal of this workshop is to have an operational Taikun project built solely with Terraform configuration files. By following a step by step process, you will discover how various Taikun resources are declared and managed using Terraform.

All your work will be done in the workshop/directory. These are its initial contents.

./workshop/
|-- main.tf
|-- taikun_auth.auto.tfvars
|-- variables.tf

main.tf contains the Provider configuration, namely its source address and what credentials to use. You will not need to edit this file.

# main.tf
terraform {
  required_providers {
    taikun = {
      source = "itera-io/taikun"
      version = "1.0.0"
    }
  }
}

provider "taikun" {
  email = var.taikun_email
  password = var.taikun_password
}

Terraform reads its configuration from all the files with the extension .tf, in the working directory. Having the provider configuration in main.tf is simply a convention.

During this workshop, each task should be coded in a separate config file. At the end of the workshop, your directory will be organized as such

./workshop/
|-- main.tf
|-- taikun_auth.auto.tfvars
|-- task0.tf
|-- task1.tf
|-- task2.tf
|-- task3.auto.tfvars
|-- task3.tf
|-- task4.tf
|-- task5.tf
|-- task6.tf
|-- task7.tf
|-- variables.tf
|-- users.auto.tfvars
|-- users.tf

Authentication #

In order to complete the tasks that follow, you will need to provide Taikun credentials to Terraform. You will need a Partner account as some of the tasks, such as creating an organization, require Partner privileges. Input variables will be explained later in the workshop. For now, simply edit taikun_auth.auto.tfvars and replace the values of taikun_email and taikun_password with your credentials.

# taikun_auth.auto.tfvars
taikun_email = "jane.doe@itera.io"
taikun_password = "PassWord123"

To find out more about providing sensitive data to Terraform, see this Hashicorp tutorial.

Task 0: Organization #

ℹ️
Info

For this task, please write your code in the file ‘task0.tf’ at the root of the workshop/directory.

This objective of this first task is to create an organization. All resources created in the future will be part of this organization. As this is the first task, every step of the process is documented.

Before you do anything, start by preparing your working directory for other commands. terraform init

?
Tip

terraform init only needs to be run once when starting a new project or after updating the list of providers to use.

If all went well, you should see the following message.

Initializing the backend...
[...]
Terraform has been successfully initialized!

Once Terraform has been initialized correctly, you can declare your organization resource. Create ‘task0.tf’ and write the following configuration block to it.

resource "taikun_organization" "myorg" {
  name = "<name>"
  full_name = "<full-name>"
  discount_rate = 120
}

Be sure to replace and with names of your choosing. You can also choose another label instead of myorg.

?
Tip

Notice the syntax of the configuration block, as you are creating a resource, it begins with the keyword resource, followed by its type between double quotes.

The type of resource is always lowercase and prefixed by the name of the provider, thus “taikun_organization”.

Following the resource’s type is a label, it must be unique for this type of resource, and is used to refer to this specific resource, as you will find out later.

Watch out, this label does not correspond to the name of the resource in Taikun

Three arguments are then defined: name, full_name and discount_rate. On the left side of the equals sign is the argument’s identifier, on the right is its value.

See the documentation of Taikun’s organization resource for a full list of arguments, i.e. the resource’s schema.

Labels and argument names can contain letters, digits, underscores and hyphens and may not start with a digit.

Run the following command to reformat your configuration in the standard style.

terraform fmt

Now apply your changes.Tip

If you have already created resources, apply will refresh Terraform’s state by making request to Taikun’s API. If you wish to check the validity of your changes without refreshing the state, you can run terraform validate.

terraform apply

You should get a validation error.

Error: expected discount_rate to be in the range (0.000000 - 100.000000), got 120.000000
Now fix the discount rate so it is in the range 0-100 and run apply once more. Terraform will display a list of
resources to create. After checking the plan is correct, type yes to execute it.
?
Tip

You should notice a file terraform.tfstate in your working directory, Terraform uses this file to keep track of the state, do not modify or delete it. You may now list the resources in Terraform’s state.

terraform state list

You can also display their content.

terraform show
taikun_organization.myorg:
resource "taikun_organization" "myorg" {
    created_at = "2021-11-05T14:00:50Z"
    discount_rate = 42
    full_name = "Jane Doe's organization"
    id = "6383"
    is_read_only = false
    lock = false
    managers_can_change_subscription = true
    name = "my-organization"
    partner_id = "119"
    partner_name = "TF-CI"
    projects = 0
    servers = 0
}

You may wish to check the organization was indeed created at app.taikun.cloud/organizations.Tip

Try running terraform apply again, Terraform will refresh its state, and, as long as nothing has changed, tell you that no changes are needed.

You can also try deleting the organization through the web UI and running terraform apply. Terraform will tell you that changes have occured outside of Terraform and recreate the resource

Task 1: Kubernetes Profile #

ℹ️
Info

For this task, please write your code in the file task1.tf at the root of the workshop/directory.

Now that you have created an organization, you will create a Kubernetes profile belonging to it. Check the kubernetes_profile resource’s schema on the provider’s documentation and declare the resource in task1.tf. Set organization_id to the ID of the organization created in the previous task (see Task 0: Organization).

Feel free to set some of kubernetes_profile’s other optional attributes, such as schedule_on_master and load_balancing_solution. Once you have declared your resource, apply your changes and move on to the next task.

?
Tip

To refer to the ID of your organization, use the following syntax. resource.taikun_organization.myorg.id Make sure to replace myorg if you used another label for your organization.

Task 2: Slack Configuration & Alerting Profile #

ℹ️
Info

For this task, please write your code in the file task2.tf at the root of the workshop/directory.

You will now create an alerting profile using a Slack configuration.

  1. Start by declaring a Slack configuration. Here is its documentation.Its hook URL should be https://hooks.myapp.example/ci. It must send alert-type notifications only to the channel ci.
  2. You can now declare the alerting profile. Here is its documentation. The alerting profile should send notifications daily using the Slack configuration declared above.
?
Tip

As always, your resources should belong to the organization created in Task 0: Organization.

Once you have declared these two new resources, apply your changes and move on to the next task.

Task 3: Cloud Credentials #

ℹ️
Info

For this task, please write your code in the file task3.tf at the root of the workshop/directory. You will also be editing task3.auto.tfvars.Important

You will need OpenStack credentials to complete this task.

Cloud credentials are needed to create a Taikun project. In a real work environment, cloud credentials should not be stored under version control Terraform’s input variables help solve this problem.

Variables are declared in variables.tf by convention. This file declares the variables taikun_email and taikun_password used for authentication.

# variables.tf
variable "taikun_email" {
  description = "Taikun email"
  type = string
  sensitive = true
}

variable "taikun_password" {
  description = "Taikun password"
  type = string
  sensitive = true
}
?
Tip

Input variables are declared with a variable block. The label that follows the variable keyword is the name of the variable.

• The description argument is used to specify the variable’s documentation. • type is the type of this argument’s value. • If set to true, sensitive will hide this variable’s value in Terraform output. It defaults to false.

To know more about input variables and a full list of arguments, see the Terraform documentation on variables.

Variables are then defined in .tfvars files, as seen in subsection Authentication.

For the sake of simplicity, variables will be declared in the task/.tf files. Thus, in task3.tf*, insert the following variable declarations

variable "openstack_url" {
  description = "OpenStack url"
  type = string
  sensitive = true
}
variable "openstack_user" {
  description = "OpenStack user"
  type = string
  sensitive = true
}
variable "openstack_password" {
  description = "OpenStack password"
  type = string
  sensitive = true
}
variable "openstack_domain" {
  description = "OpenStack domain"
  type = string
  sensitive = true
}
variable "openstack_region" {
  description = "OpenStack region"
  type = string
}
variable "openstack_public_network" {
  description = "OpenStack public network"
  type = string
}
variable "openstack_project" {
  description = "OpenStack project name"
  type = string
}
ℹ️
Info

If copy-pasting this code block into task3.tf does not indent the code properly, save task3.tf and run terraform fmt.

Now that the OpenStack variables have been declared, define the variables in task3.auto.tfvars using your credentials.

Terraform must be told through command line arguments which .tfvars files to read. However, if variable definition files have the extension .auto.tfvars, as is the case with taikun_auth.auto.tfvars, Terraform will automatically fetch the variables’ values.

?
Tip

As a reminder, here is the syntax used in taikun_auth.auto.tfvars to define the variables taikun_email and taikun_password.

taikun_email = "jane.doe@itera.io"
taikun_password = "PassWord123"
?
Tip

In order to get a variable’s value, use the syntax var.. For example, the following line sets the OpenStack domain in the cloud_credential_openstack resource.

domain = var.openstack_domain

Once you have declared your new resource, apply your changes and move on to the next task.

ℹ️
Info

As always, your resources should belong to the organization created in Task 0: Organization

Task 4: Users #

?
Note

For this task, please write your code in the file task4.tf at the root of the workshop/directory. You will also be editing users.tf and users.auto.tfvars.

You will now add users to the Taikun organization. As the organization could have a large amount of users, you will use variables and the keyword for_each to avoid declaring multiple taikun_user blocks.

Add the following variable declaration to users.tf.

variable "users" {
  type = map(object({
    email = string
    role = string
   }))
   description = "List of project users"
   default = {}
}

The users variable is of a complex type: a map of objects with two arguments, email and role. The keys of the map are strings, they will be the usernames of the users. The default = {} argument definition tells Terraform that the default value of var.users is an empty map.

Here is an example definition of the users variable.

users = {
  "alice" = {
    email = "alice@gmail.com"
    role = "Manager"
  },
  "bob" = {
    email = "bob@gmail.com"
    role = "User"
  },
}

In this example, user accounts are defined for Alice and Bob. • Alice has a Manager account with the username alice and the email alice@gmail.com. • Bob has a User account with the username bob and the email bob@gmail.com.

Now edit users.auto.tfvars and define three users. • -manager with Manager role and the email -manager@mail.example. • -user1 with User role and the email -user1@mail.example. • -user2 with User role and the email -user2@mail.example.

Replace with a name of your choosing.

You can now declare the user resource in task4.tf, the users must belong to the organization created in Task 0: Organization. Here is its documentation. By using the for_each keyword, only one resource block is needed.

?
Tip

Here is an example using the for_each keyword. Consider a Terraform provider to order pizzas. Sup- pose the variable pizza_orders has the following definition.

pizza_orders = {
  "alice" = {
    type = "pepperoni"
    size = "large"
   },
   "bob" = {
     type = "amatriciana"
     size = "medium"
   },
}

Here is how it would be used with the for_each keyword in a pizza_order resource.

resource "pizza_order" "orders" {
  for_each = var.pizza_orders
  client = each.key
  type = each.value.type
  size = each.value.size
}

You can also have a look at Terraform’s for_each documentation.

Once you have declared the user resource, apply your changes and move on to the next task.

Task 5: Access Profile #

?
Note

For this task, please write your code in the file task5.tf at the root of the workshop/directory. You will also be editing users.tf and users.auto.tfvars.

Before creating your first project, you will need an access profile.

The access profile must contain SSH keys for all the users created in the previous task, Task 4: Users. Rather than declare the SSH keys in a separate variable, you will add them to the users variable to declare them on per user basis.

Modify users’s declaration in users.tf to include a list of SSH users per user.

variable "users" {
  type = map(object({
    email = string
    role = string
    ssh_users = list(object({
      name = string
      public_key = string
    }))
   }))
   description = "List of project users"
   default = {}
}

You can now edit users.auto.tfvars and define a list of SSH users for each user. Considering the previous example of Alice and Bob, here is the same definition of users with added SSH users.

users = {
  "alice" = {
    email = "alice@gmail.com"
    role = "Manager"
    ssh_users = [
      {
        name = "alice-work"
        public_key = "ssh-ed25519 AAAATHEQUICKBROWNFOXJUMPEDOVERTHELAZYDOG example"
      },
      {
        name = "alice-home"
        public_key = "ssh-ed25519 AAAATHEQUICKBROWNFOXJUMPEDOVERTHELAZYDOG example"
      }
     ]
    },
    "bob" = {
      email = "bob@gmail.com"
      role = "User"
      ssh_users = [
        {
          name = "bob-laptop"
          public_key = "ssh-ed25519 AAAATHEQUICKBROWNFOXJUMPEDOVERTHELAZYDOG example"
        }
       ]
      },
     }

Add as many SSH users as you wish to the users defined in the previous task. Of course, you will need to use valid SSH keys. If you do not wish to create your own, here is a public key value you can use:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIB/8P0zXmI/Il81+/fnvGrf0X/VyNTrOJ9nQCxBxjc5m taikun
ℹ️
Info

Within one access profile, the names of SSH users must be unique.

You can now declare the taikun_access_profile resource in task5.tf. You will use for_each in a slightly different manner as ssh_user is a nested resource within the access_profile resource. Here is the documentation of the access profile resource.

The access profile’s requirements are: • It should use the DNS servers 8.8.8.8 and 1.1.1.1. • It should use the NTP server time.windows.com. • It should include all the SSH users defined in users.auto.tfvars.

?
Tip

While reading access profile’s schema, you may notice dns_server and ntp_server are of the type Block List.

Going back to the pizza order example, here is how block lists are used. Suppose the pizza_order resource has an argument extra_topping defined as such:

 - extra_topping (Block List, Max: 5) List of extra pizza toppings. (see below for nested
 schema)

 Nested Schema for extra_topping
 Required:
 - name (String) Name of the extra topping
 - quantity (Number) Quantity

Here is how Alice could add mozzarella di bufala and basil to her amatriciana pizza order.

resource "pizza_order" "orders" {
  client = "alice"
  type = "amatriciana"
  size = "large"

  extra_topping {
    name = "basil leaves"
    quantity = 8
  }
  extra_topping {
    name = "bufala slices"
    quantity = 4
  }
}
?
Note

Spoiler ahead!

Solution: Add the following dynamic “ssh_user” block to your access profile’s configuration.

resource "taikun_access_profile" "..." {

   # Rest of configuration: DNS servers, NTP servers, etc.
   # ...

   dynamic "ssh_user" {
     for_each = flatten([for user in var.users : user.ssh_users])
     content {
       name = ssh_user.value.name
       public_key = ssh_user.value.public_key
     }
    }
}

Once you have fully declared the access profile resource, apply your changes and move on to the next task.

Task 6: Project #

?
Note

For this task, please write all your code in the file task6.tf at the root of the workshop/directory.

Finally, you can declare a project resource. However, as flavors must be bound to the project, you must first fetch a list of suitable flavors.

To do this, declare a flavors datasource. Datasources, as opposed to resources, only fetch information from providers and do not create any resources. Add the following block to task6.tf.

data "taikun_flavors" "small" {
# FIXME
}
?
Tip

As you are declaring a datasource and not a resource, the block begins with the keyword data instead of resource. Once again, the type of datasource is in lowercase and must be prefixed by the name of the provider. Finally, the label “small” is used to designate this datasource.

Edit the datasource to search for flavors with 4 or fewer CPUs and no more than 8GB of RAM. Set its cloud credential ID to that of the cloud credential created in Task 3: Cloud Credentials.

Then declare a local value flavors to be the list of names of the flavors read by the datasource. See the Terraform documentation to know more about local values.

locals {
  flavors = [for flavor in data.taikun_flavors.small.flavors : flavor.name]
}

This will allow you to refer to the list of flavor names with local.flavors, which will be useful when defining the project.

You now have everything you need to create a project in Taikun. Here is its documentation.

These are the requirements for the project resource: • As all previous resources, it must belong to the organization created in Task 0: Organization. • It must use the kubernetes profile defined in Task 1: Kubernetes Profile. • Its alerting profile must be the one defined in Task 2: Slack Configuration & Alerting Profile. • It should use the cloud credentials defined in Task 3: Cloud Credentials. • Monitoring must be enabled. • It should have one bastion, one kubemaster and one kubeworker.

?
Tip

To access the first element of a list, use the syntax list[index]. For example, to get the first flavor read by the flavors datasource, use local.flavors[0].

After creating a project with Terraform, one may want to know its access IP. Once you have declared the project resource, add the following output block to task6.tf.

output "project_access_ip" {
  value = resource.taikun_project.<project-label>.access_ip
}

Make sure to replace with the label you gave your project. This will display the project’s access IP once it has been created.-

?
Tip

Output values are a way for the user to output a specific value from Terraform’s state.

An output value block begins with the keyword output followed by a unique label. By setting the value argument, the user can decide which value to output.

To know more about output values, see Terraform’s documentation.

You can now apply your changes; expect to wait about 30 minutes for your project to be in Ready state.

Task 7: Project User Attachments #

?
Note

For this task, please write all your code in the file task7.tf at the root of the workshop/directory.

Now that your project is in Ready state, you can attach some users to it.

Declare a project user attachment resource with the following for_each argument, replacing with the label you gave the taikun_user resource.

for_each = {
  for user in resource.taikun_user.<label> : user.id => user
  if user.role == "User"
}

With this block, you will be able to attach only users with the User role to the project. To know more about this syntax, see the documentation on for expressions.

Finally, set the proper values for the user_id and **project_id arguments and apply your changes.

Taikun-CLI #

Taikun Cli Go #

 User  ?Manager  ?Partner

Manage resources in Taikun from the command line.

Getting started Downloading the binary To download the CLI, head to the latest release page

Scroll down to the Assets section and select the binary for your architecture.

Signing in to Taikun The Taikun CLI reads environment variables to authenticate to Taikun.

To authenticate with your Taikun account, set the following environment variables:

TAIKUN_EMAIL
TAIKUN_PASSWORD

To authenticate with Keycloak, set the following environment variables:

TAIKUN_KEYCLOAK_EMAIL
TAIKUN_KEYCLOAK_PASSWORD

The default API host is api.taikun.cloud. To override it, set the following environment variable:

TAIKUN_API_HOST (default value is: api.taikun.cloud)

Run the following command to check whether you are properly authenticated.

taikun whoami Setting up autocompletion Autocompletion is available for the following shells.

Bash
Zsh
Fish
PowerShell

The command taikun completion generates an autocompletion script for the specified shell. For instructions on how to use the generated script, see the help command of the corresponding shell.

For example, taikun completion bash -h provides instructions on how to set up autocompletion for the Bash shell.

Command overview To have an overview of all the commands available, see the generated command tree

Help To get information on how to use a command, type taikun [command] –help or taikun [command] -h for short.

What are your feelings