Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve instructions to use the 3rd-party plugin directory #35

Merged
merged 1 commit into from
Mar 3, 2019
Merged

Improve instructions to use the 3rd-party plugin directory #35

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 42 additions & 30 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,49 @@
# Terraform Provider for Container Linux Configs
# terraform-provider-ct

The `ct` provider provides a `ct_config` data source that parses a [Container Linux Config](https://github.com/coreos/container-linux-config-transpiler/blob/master/doc/configuration.md), validates the content, and renders [Ignition](https://github.com/coreos/ignition). The rendered strings can be used as input to other Terraform resources (e.g. user-data for instances).
`terraform-provider-ct` allows defining a `ct_config` [Container Linux Config](https://github.com/coreos/container-linux-config-transpiler/blob/master/doc/configuration.md) resource to validate the content and render an [Ignition](https://github.com/coreos/ignition) document. Rendered Ignition may be used as input to other Terraform resources (e.g. instance user-data).

## Ignition schema output

Each minor version of `terraform-provider-ct` is tightly coupled with a minor version of the Ignition schema. Ignition transparently handles old Ignition schema versions, so this isn't normally an issue.

However, it is **not safe** to upgrade between minor versions on existing managed clusters. Minor version upgrades of this plugin **will re-provision your cluster** because the Ignition config output has changed.
## Requirements

| `terraform-provider-ct` | Ignition schema version |
| ----------------------- | ----------------------- |
| 0.2.x | 2.0 |
| 0.3.x | 2.2 |
* Terraform v0.11+ [installed](https://www.terraform.io/downloads.html)

## Requirements
## Install

* Terraform 0.9.x
Add the `terraform-provider-ct` plugin binary for your system to the Terraform 3rd-party [plugin directory](https://www.terraform.io/docs/configuration/providers.html#third-party-plugins) `~/.terraform.d/plugins`.

## Installation
```sh
VERSION=v0.3.0
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docker friendly snippet:

ENV TERRAFORM_PROVIDER_RKE_VERSION=0.9.0
RUN mkdir -p .terraform/plugins/linux_amd64 && \
    wget https://github.com/coreos/terraform-provider-ct/releases/download/v${TERRAFORM_PROVIDER_CT_VERSION}/terraform-provider-ct-v${TERRAFORM_PROVIDER_CT_VERSION}-linux-amd64.tar.gz -O - | tar -xzvf - terraform-provider-ct-v${TERRAFORM_PROVIDER_CT_VERSION}-linux-amd64/terraform-provider-ct --strip-components=1 && \
    mv ./terraform-provider-ct .terraform/plugins/linux_amd64/terraform-provider-ct_v${TERRAFORM_PROVIDER_CT_VERSION}_x4

wget https://github.com/coreos/terraform-provider-ct/releases/download/$VERSION/terraform-provider-ct-$VERSION-linux-amd64.tar.gz
tar xzf terraform-provider-ct-$VERSION-linux-amd64.tar.gz
mv terraform-provider-ct-$VERSION-linux-amd64/terraform-provider-ct ~/.terraform.d/plugins/terraform-provider-ct_$VERSION
```

Add the `terraform-provider-ct` plugin binary on your filesystem.
Terraform plugin binary names are versioned to allow for migrations of managed infrastructure.

```
# dev
go get -u github.com/coreos/terraform-provider-ct
$ tree ~/.terraform.d/
/home/user/.terraform.d/
└── plugins
├── terraform-provider-ct_v0.2.1
└── terraform-provider-ct_v0.3.0
```

Register the plugin in `~/.terraformrc`.
## Usage

Configure the ct provider in a `providers.tf` file.

```hcl
providers {
ct = "/$GOPATH/bin/terraform-provider-ct"
provider "ct" {
version = "0.3.0"
}
```

## Usage
Run `terraform init` to ensure plugin version requirements are met.

```
$ terraform init
```

Declare a `ct_config` resource in Terraform.

```hcl
data "ct_config" "worker" {
Expand All @@ -53,24 +62,27 @@ resource "aws_instance" "worker" {
}
```

The optional platform can be "azure", "ec2", "gce", or [others](https://github.com/coreos/container-linux-config-transpiler/blob/master/config/platform/platform.go) to perform platform-specific susbstitutions. By default, platform is "" (none, for bare-metal).
Set the `content` to the contents of a Container Linux Config that should be validated and rendered as Ignition. Optionally, use the `snippets` field to append a list of Container Linux Config snippets. Use `platform` if [platform-specific](https://github.com/coreos/container-linux-config-transpiler/blob/master/config/platform/platform.go) susbstitution is desired.

### Ignition schema output

Each minor version of `terraform-provider-ct` is tightly coupled with a minor version of the Ignition schema. Ignition transparently handles old Ignition schema versions, so this isn't normally an issue.

Upgrading between versions for existing managed clusters **may not be safe**. Check your usage to determine whether a `user_data` change to an instance would re-provision a machine (important machines may be configured to ignore `user_data` changes).

The `snippets` field is an optional list of Container Linux Config snippets that are appended to the main config specified in `content` before being rendered into an Ignition config.
| terraform-provider-ct | Ignition schema version |
|-----------------------|-------------------------|
| 0.2.x | 2.0 |
| 0.3.x | 2.2 |

## Development

### Binary

To develop the provider plugin locally, build an executable with Go v1.11+.

```sh
make
```

Optionally, install the plugin to `$(GOPATH)/bin`.

```sh
make install
make
```

### Vendor
Expand Down