Skip to content

Commit

Permalink
Merge pull request #16 from muvaf/metadata-fixes
Browse files Browse the repository at this point in the history 
docs: small fixes
  • Loading branch information
@muvaf
muvaf authored Dec 5, 2022
2 parents 3ab02ff + c1dc8b2 commit 53c4d5d
Show file tree
Hide file tree
Showing 3 changed files with 97 additions and 61 deletions.
75 changes: 44 additions & 31 deletions docs/Configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,25 @@
title: Configuration
weight: 2
---
# Configuring official Terraform provider
# Configuration Options

There are several ways to provide configurations to the official Terraform
provider that will propagate to the underlying Terraform workspace. In the
following sections, we will cover the most common ones.

## IAM Roles for Service Accounts (IRSA)

You can setup the Terraform Provider using AWS [IAM Roles for Service Accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html).
For more information, check out the example [setup](./examples/aws-eks-irsa-seup.yaml), the process is similar to what
you would use for the [provider-aws](https://github.com/upbound/provider-aws/blob/master/AUTHENTICATION.md#using-iam-roles-for-serviceaccounts).
You can setup the Terraform Provider using AWS [IAM Roles for Service Accounts
(IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html).
For more information, check out the example
[setup](./examples/aws-eks-irsa-seup.yaml), the process is similar to what you
would use for the
[provider-aws](https://github.com/upbound/provider-aws/blob/master/AUTHENTICATION.md#using-iam-roles-for-serviceaccounts).

## Private Git repository support

To securely propagate git credentials create a `git-credentials` secret in [git credentials store] format.
To securely propagate git credentials create a `git-credentials` secret in [git
credentials store] format.

```sh
cat .git-credentials
Expand Down Expand Up @@ -44,19 +52,20 @@ controller will be able to automatically pick it up.

## Terraform Output support

Non-sensitive outputs are mapped to the status.atProvider.outputs section
as strings so they can be referenced by the Composition.
Strings, numbers and booleans can be referenced directly in Compositions
and can be used in the _convert_ transform if type conversion is needed.
Tuple and object outputs will be available in the corresponding JSON form.
This is required because undefined object attributes are not specified in the Workspace
CRD and so will be sanitized before the status is stored in the database.
Non-sensitive outputs are mapped to the status.atProvider.outputs section as
strings so they can be referenced by the Composition. Strings, numbers and
booleans can be referenced directly in Compositions and can be used in the
_convert_ transform if type conversion is needed. Tuple and object outputs will
be available in the corresponding JSON form. This is required because undefined
object attributes are not specified in the Workspace CRD and so will be
sanitized before the status is stored in the database.

That means that any output values required for use in the Composition must be published
explicitly and individually, and they cannot be referenced inside a tuple or object.
That means that any output values required for use in the Composition must be
published explicitly and individually, and they cannot be referenced inside a
tuple or object.

For example, the following terraform outputs:
```yaml
```hcl
output "string" {
value = "bar"
sensitive = false
Expand Down Expand Up @@ -98,8 +107,8 @@ Appear in the corresponding outputs section as:
Note that the "sensitive" output is not included in status.atProvider.outputs
## Terraform CLI Command Arguments
Additional arguments can be passed to the Terraform plan, apply, and destroy commands by specifying
the planArgs, applyArgs and destroyArgs options.
Additional arguments can be passed to the Terraform plan, apply, and destroy
commands by specifying the planArgs, applyArgs and destroyArgs options.
For example:
```yaml
Expand Down Expand Up @@ -129,15 +138,17 @@ spec:
namespace: default
name: terraform-workspace-example-inline
```
This will cause the _terraform init_ command to be run with the "-upgrade=true" argument,
the _terraform plan_ command to be run with the -parallelism=2 argument,
the _terraform apply_ command to be run with the -target=specificresource argument,
and the _terraform destroy_ command to be run with the -refresh=false argument.
Note that by default the terraform _init_ command is run with the "-input=false", and "-no-color" arguments,
the terraform _apply_ and _destroy_ commands are run with the
"-no-color", "-auto-approve", and "-input=false" arguments, and the terraform _plan_ command is
run with the "-no-color", "-input=false", and "-detailed-exitcode" arguments. Arguments specified in
This will cause the _terraform init_ command to be run with the "-upgrade=true"
argument, the _terraform plan_ command to be run with the -parallelism=2
argument, the _terraform apply_ command to be run with the
-target=specificresource argument, and the _terraform destroy_ command to be run
with the -refresh=false argument.
Note that by default the terraform _init_ command is run with the
"-input=false", and "-no-color" arguments, the terraform _apply_ and _destroy_
commands are run with the "-no-color", "-auto-approve", and "-input=false"
arguments, and the terraform _plan_ command is run with the "-no-color",
"-input=false", and "-detailed-exitcode" arguments. Arguments specified in
applyArgs, destroyArgs and planArgs will be added to these default arguments.
## Custom Entrypoint for Terraform Invocation
Expand Down Expand Up @@ -198,8 +209,8 @@ spec:

## Enable External Secret Support

If you need to store the sensitive output to an external secret store like Vault,
you can specify the `--enable-external-secret-stores` flag to enable it:
If you need to store the sensitive output to an external secret store like
Vault, you can specify the `--enable-external-secret-stores` flag to enable it:

```yaml
apiVersion: pkg.crossplane.io/v1alpha1
Expand Down Expand Up @@ -270,7 +281,9 @@ spec:
name: vault
```

At Vault side configuration is also needed to allow the write operation,
see [example](https://crossplane.io/docs/v1.9/guides/vault-as-secret-store.html#prepare-vault) here for inspiration.
At Vault side configuration is also needed to allow the write operation, see
[example](https://crossplane.io/docs/v1.9/guides/vault-as-secret-store.html#prepare-vault)
here for inspiration.

A concrete provider terraform use case is also available [here](https://github.com/crossplane-contrib/provider-terraform/pull/101).
A concrete provider terraform use case is also available
[here](https://github.com/crossplane-contrib/provider-terraform/pull/101).
73 changes: 48 additions & 25 deletions docs/Quickstart.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,18 @@ weight: 1
---
# Quickstart

This guide walks through the process to install Upbound Universal Crossplane and install the Terraform official provider.
The official Terraform Provider allows you to write Terraform HCL configuration
as the desired configuration for your infrastructure. It allows you to use your
existing Terraform modules from different sources and still get the experience
of using Crossplane with all the features like automatic drift correction,
composition and others.

To use this official provider, install Upbound Universal Crossplane into your Kubernetes cluster, install the `Provider`, apply a `ProviderConfig`, and create a *managed resource* of type `Workspace` via Kubernetes.
This guide walks through the process to install Upbound Universal Crossplane and
install the Terraform official provider.

To use this official provider, install Upbound Universal Crossplane into your
Kubernetes cluster, install the `Provider`, apply a `ProviderConfig`, and create
a *managed resource* of type `Workspace` via Kubernetes.

## Install the Up command-line
Download and install the Upbound `up` command-line.
Expand All @@ -23,7 +32,8 @@ $ up --version
v0.13.0
```

_Note_: official providers only support `up` command-line versions v0.13.0 or later.
_Note_: official providers only support `up` command-line versions v0.13.0 or
later.

## Install Universal Crossplane
Install Upbound Universal Crossplane with the Up command-line.
Expand All @@ -46,7 +56,8 @@ xgql-8fb949dcf-pxn4z 1/1 Running 3 (52s ago) 93s

## Install the official Terraform provider

Install the official provider into the Kubernetes cluster with a Kubernetes configuration file.
Install the official provider into the Kubernetes cluster with a Kubernetes
configuration file.

```yaml
apiVersion: pkg.crossplane.io/v1
Expand All @@ -70,11 +81,14 @@ provider-terraform True True xpkg.upbound.io/upbound/provider-terr
It may take up to 5 minutes to report `HEALTHY`.

## Create a Kubernetes secret
The provider requires credentials to create and manage cloud resources. In this guide, we will work with GCP as an
example, but the process is the same for any cloud provider.
The provider requires credentials to create and manage cloud resources. In this
guide, we will work with GCP as an example, but the process is the same for any
cloud provider.

### Generate a GCP JSON key file
Create a JSON key file containing the GCP account credentials. GCP provides documentation on [how to create a key file](https://cloud.google.com/iam/docs/creating-managing-service-account-keys).
Create a JSON key file containing the GCP account credentials. GCP provides
documentation on [how to create a key
file](https://cloud.google.com/iam/docs/creating-managing-service-account-keys).

Here is an example key file:

Expand All @@ -96,15 +110,18 @@ Here is an example key file:
Save this JSON file as `gcp-credentials.json`.

### Create a Kubernetes secret with GCP credentials
Use `kubectl create secret -n upbound-system` to generate the Kubernetes secret object inside the Universal Crossplane cluster.
Use the following command to create the Kubernetes secret object in the cluster.

`kubectl create secret generic gcp-creds -n upbound-system --from-file=credentials=./gcp-credentials.json`
```
kubectl create secret generic tf-gcp-creds -n upbound-system \
--from-file=credentials=./gcp-credentials.json
```
View the secret with `kubectl describe secret`
View the secret with `kubectl describe secret tf-gcp-creds -n upbound-system`
```shell
$ kubectl describe secret gcp-creds -n upbound-system
Name: gcp-creds
Name: tf-gcp-creds
Namespace: upbound-system
Labels: <none>
Annotations: <none>
Expand All @@ -118,9 +135,11 @@ credentials: 2380 bytes

## Create a ProviderConfig

Create a `ProviderConfig` Kubernetes configuration file to attach the GCP credentials to the installed official provider.
Create a `ProviderConfig` Kubernetes configuration file to attach the GCP
credentials to the installed official provider.

**Note:** the `ProviderConfig` must contain the correct GCP project ID. The project ID must match the `project_id` from the JSON key file.
**Note:** the `ProviderConfig` must contain the correct GCP project ID. The
project ID must match the `project_id` from the JSON key file.

```yaml
apiVersion: tf.upbound.io/v1beta1
Expand All @@ -137,7 +156,7 @@ spec:
source: Secret
secretRef:
namespace: upbound-system
name: gcp-creds
name: tf-gcp-creds
key: credentials
# This optional configuration block can be used to inject HCL into any
# workspace that uses this provider config, for example to setup Terraform
Expand All @@ -160,7 +179,9 @@ spec:
Apply this configuration with `kubectl apply -f`.

**Note:** the `ProviderConfig` value `spec.credentials[0].secretRef.name` must match the `name` of the secret in `kubectl get secrets -n upbound-system` and `spec.secretRef.key` must match the value in the `Data` section of the secret.
**Note:** the `ProviderConfig` value `spec.credentials[0].secretRef.name` must
match the `name` of the secret in `kubectl get secrets -n upbound-system` and
`spec.secretRef.key` must match the value in the `Data` section of the secret.

Verify the `ProviderConfig` with `kubectl describe providerconfigs`.

Expand Down Expand Up @@ -196,7 +217,8 @@ Spec:
```

## Create a `Workspace` resource
Create a managed resource of type `Workspace` to verify the provider is functioning.
Create a managed resource of type `Workspace` to verify the provider is
functioning.

This example creates a GCP storage bucket with a globally unique name.

Expand All @@ -206,13 +228,10 @@ kind: Workspace
metadata:
name: example-inline
annotations:
meta.upbound.io/example-id: tf/v1beta1/workspace
# The terraform workspace will be named 'coolbucket'. If you omit this
# annotation it would be derived from metadata.name - e.g. 'example-inline'.
crossplane.io/external-name: coolbucket
spec:
providerConfigRef:
name: default
forProvider:
# Workspaces default to using a remote source - like workspace-remote.yaml.
# For simple cases you can use an inline source to specify the content of
Expand Down Expand Up @@ -242,7 +261,8 @@ spec:
name: terraform-workspace-example-inline
```

**Note:** the `spec.providerConfigRef.name` must match the `ProviderConfig` `metadata.name` value.
**Note:** the `spec.providerConfigRef.name` must match the `ProviderConfig`
`metadata.name` value.

Apply this configuration with `kubectl apply -f`.

Expand All @@ -254,15 +274,18 @@ NAME READY SYNCED AGE
example-inline True True 46s
```

Provider applied the core in the workspace when the values `READY` and `SYNCED` are `True`. Since the workspace
resource we configured creates a `google_storage_bucket` resource, we can verify that the bucket was created by
Provider applied the core in the workspace when the values `READY` and `SYNCED`
are `True`. Since the workspace resource we configured creates a
`google_storage_bucket` resource, we can verify that the bucket was created by
checking the GCP console.

If the `READY` or `SYNCED` are blank or `False` use `kubectl describe` to understand why.
If the `READY` or `SYNCED` are blank or `False` use `kubectl describe` to
understand why.

## Delete the managed resource
Remove the workspace by using `kubectl delete -f` with the same `Workspace` object file.
The provider triggers a `terraform destroy` and removes the bucket with the deletion of the `Workspace` resource.
Remove the workspace by using `kubectl delete -f` with the same `Workspace`
object file. The provider triggers a `terraform destroy` and removes the bucket
with the deletion of the `Workspace` resource.

Verify the removal of the bucket with `kubectl get workspace`.

Expand Down
10 changes: 5 additions & 5 deletions package/crossplane.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@ metadata:
meta.crossplane.io/maintainer: Upbound <[email protected]>
meta.crossplane.io/source: github.com/upbound/provider-terraform
meta.crossplane.io/description: |
The Terraform Crossplane provider enables management of Terraform
modules by defining Crossplane Composite Resources.
Upbound's official Crossplane provider to manage Terraform workspaces.
meta.crossplane.io/readme: |
The Terraform provider adds support for a Workspace managed resource
that represents a Terraform workspace. The configuration of each workspace
may be either fetched from a remote source (e.g. git), or simply specified inline.
Provider Terraform is a Crossplane provider that lets you manage resources
using virtual Terraform workspaces. It is developed and supported by
Upbound. Available resources and their fields can be found in the [Upbound
Marketplace](https://marketplace.upbound.io/providers/upbound/provider-terraform).
friendly-name.meta.crossplane.io: Provider Terraform

0 comments on commit 53c4d5d

Please sign in to comment.