Quick start
While all actions can be performed via kubectl, Terranetes comes bundled with a CLI tool to make operations quicker. You can find the download on releases
Before we begin, you'll need the following tools:
The quickest way to get up and running is via the Helm chart (see chart):
$ helm repo add appvia https://terranetes-controller.appvia.io
$ helm repo update
$ kind create cluster
$ helm install -n terraform-system terranetes-controller appvia/terranetes-controller --create-namespace
$ kubectl -n terraform-system get pods
Configure credentials
Next, we configure some cloud credentials to run terraform with (see provider.yaml):
The following assumes you are using static cloud credentials. See the docs for managed pod identity.
$ kubectl -n terraform-system create secret generic aws \
--from-literal=AWS_ACCESS_KEY_ID=<ID> \
--from-literal=AWS_SECRET_ACCESS_KEY=<SECRET> \
--from-literal=AWS_REGION=<REGION>
$ kubectl apply -f https://raw.githubusercontent.com/appvia/terranetes-controller/master/examples/provider.yaml
$ kubectl get provider -o yaml
See Configure Credentials for more details.
Configure a Revision
The following example uses a pre-baked Revision, however, for tips on generating Revisions please go here
Retrieve a demo revision that creates an S3 bucket (see revision.yaml).
wget https://raw.githubusercontent.com/appvia/terranetes-controller/master/examples/revision.yaml
Next, lets create a Revision for the resource.
# View the contains of the revision for the s3 bucket
$ cat revision.yaml # demo for provisioning an s3 bucket
# Apply the revision
$ kubectl apply -f revision.yaml
$ kubectl get revision
# We should have a plan from the new revision
$ kubectl get plan
Provision a Cloud Resource
Lets retrieve the cloud resource example from here
wget https://raw.githubusercontent.com/appvia/terranetes-controller/master/examples/cloudresource.yaml
You can also run tnctl create cloudresource to generate a CloudResource CRD from a Revision
Lets create a namespace, and consume the revision.
# Create the namespace
$ kubectl create namespace apps
# Ensure you change any 'CHANGE_ME' variables in the example
$ vim cloudresource.yaml
# Create the cloudresource
$ kubectl -n apps apply -f cloudresource.yaml
$ kubectl -n apps get po
# Straight away a job is created to 'watch' the terraform workflow
$ kubectl -n apps logs -f <POD_ID>
You can use the tnctl logs cloudresource --namespace apps bucket --follow to find and watch the logs from a build, instead of kubectl commands.
Approve the plan
By default, unless the spec.enableAutoApproval is true, all changes must be approved before acting on. An annotation is used to approve the previous plan.
If you are using the tnctl cli, you can approve changes via tnctl approve cloudresource --namespace apps bucket
kubectl -n apps annotate cloudresources bucket "terraform.appvia.io/apply"=true --overwrite
Another kubernetes job will be created to watch the execution of the terraform apply, you can view the logs via kubectl -n apps get po | grep apply, get the pod name and tail the logs kubectl -n apps logs -f <NAME>.
The actual terraform execution does not occur in the apps namespace, users simply have the ability to watch the output of the run. The job and the credentials never leave the platform teams namespace terraform-system
View the the CloudResource below.
$ kubectl -n apps get cloudresources.terraform.appvia.io
NAME PLAN REVISION SECRET CONFIGURATION ESTIMATED UPDATE SYNCHRONIZED AGE
bucket bucket v0.0.1 test bucket-7v8jp Not Enabled None InSync 2m7s
# View the kubernetes secrets containing the outputs
$ kubectl -n apps get secret test -o yaml
For a complete summary of CloudResources click here.
Deleting the terraform resources
You can delete the cloud resource like any other Kubernetes resource
kubectl -n apps delete cloudresource bucket --wait=false
Tailing the logs from the watcher will allow you to view the execution.
POD_NAME=$(kubectl -n apps get pods -l terraform.appvia.io/stage=destroy --no-headers | cut -d' ' -f1)
kubectl -n apps logs ${POD_NAME} -f
Or via tnctl
tnctl logs cloudresource -n apps bucket -f