Skip to content
This repository was archived by the owner on Aug 11, 2021. It is now read-only.

Changes for Beta release #234

Open
jrhouston wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Changes for Beta release #234

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6eeb67e
Remove experimental language from docs
jrhouston May 31, 2021
a899b1f
Tidy up configuration docs
jrhouston Jun 15, 2021
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
41 changes: 17 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,24 @@
# Kubernetes provider for Terraform (alpha)
# Kubernetes-alpha provider for Terraform

<a href="https://terraform.io">
<img src="https://cdn.rawgit.com/hashicorp/terraform-website/master/content/source/assets/images/logo-hashicorp.svg" alt="Terraform logo" align="right" height="50" />
</a>


![Status: Experimental](https://img.shields.io/badge/status-experimental-EAAA32) [![Releases](https://img.shields.io/github/release/hashicorp/terraform-provider-kubernetes-alpha.svg)](https://github.com/hashicorp/terraform-provider-kubernetes-alpha/releases)
![Status: Beta](https://img.shields.io/badge/status-beta-EAAA32) [![Releases](https://img.shields.io/github/release/hashicorp/terraform-provider-kubernetes-alpha.svg)](https://github.com/hashicorp/terraform-provider-kubernetes-alpha/releases)
[![LICENSE](https://img.shields.io/github/license/hashicorp/terraform-provider-kubernetes-alpha.svg)](https://github.com/hashicorp/terraform-provider-kubernetes-alpha/blob/master/LICENSE)
![unit tests](https://github.com/hashicorp/terraform-provider-kubernetes-alpha/workflows/unit%20tests/badge.svg)
![acceptance tests](https://github.com/hashicorp/terraform-provider-kubernetes-alpha/workflows/acceptance%20tests/badge.svg)

This Kubernetes provider for Terraform (alpha) supports all API resources in a generic fashion.

This provider allows you to describe any Kubernetes resource using HCL. See [Moving from YAML to HCL](#moving-from-yaml-to-hcl) if you have YAML you want to use with the provider.
This Terraform provider offers a dynamic interface that enables support for any Kubernetes API resource, including Custom Resources.

Please regard this project as experimental. It still requires extensive testing and polishing to mature into production-ready quality. At this time, we are not planning to create a migration path for resources created with the kubernetes-alpha provider when the `manifest` resource is merged into the official kubernetes provider. For this reason, please do not rely on this provider for production use while we strive towards project maturity. Please [file issues](https://github.com/hashicorp/terraform-provider-kubernetes-alpha/issues/new/choose) generously and detail your experience while using the provider. We welcome your feedback.
The provider allows any Kubernetes resource to be codified using HCL. See [Moving from YAML to HCL](#moving-from-yaml-to-hcl) if you have existing YAML you want to use with Terraform.

Our eventual goal is for this generic resource to become a part of our [official Kubernetes provider](https://github.com/hashicorp/terraform-provider-kubernetes) once it is supported by the Terraform Plugin SDK. However, this work is subject to signficant changes as we iterate towards that level of quality.
This project is currently in beta. Please [file issues](https://github.com/hashicorp/terraform-provider-kubernetes-alpha/issues) generously.

## Requirements

* [Terraform](https://www.terraform.io/downloads.html) version 0.14.8 +
* [Kubernetes](https://kubernetes.io/docs/reference) version 1.17.x +
* [Go](https://golang.org/doc/install) version 1.14.x
* [Terraform](https://www.terraform.io/downloads.html) version 0.14.8+
* [Kubernetes](https://kubernetes.io/docs/reference) version 1.17.x+
* [Go](https://golang.org/doc/install) version 1.14.x+

## Getting Started

Expand All @@ -33,11 +30,11 @@ Once you have the plugin installed, review the [usage document](https://github.c

### Create a Kubernetes ConfigMap
```hcl
provider "kubernetes-alpha" {
provider kubernetes-alpha {
config_path = "~/.kube/config" // path to kubeconfig
}

resource "kubernetes_manifest" "test-configmap" {
resource kubernetes_manifest test-configmap {
provider = kubernetes-alpha

manifest = {
Expand All @@ -57,11 +54,11 @@ resource "kubernetes_manifest" "test-configmap" {
### Create a Kubernetes Custom Resource Definition

```hcl
provider "kubernetes-alpha" {
provider kubernetes-alpha {
config_path = "~/.kube/config" // path to kubeconfig
}

resource "kubernetes_manifest" "test-crd" {
resource kubernetes_manifest test-crd {
provider = kubernetes-alpha

manifest = {
Expand Down Expand Up @@ -107,7 +104,7 @@ The `kubernetes_manifest` resource supports the ability to block create and upda
`wait_for` currently supports a `fields` attribute which allows you specify a map of fields paths to regular expressions. You can also specify `*` if you just want to wait for a field to have any value.

```hcl
resource "kubernetes_manifest" "test" {
resource kubernetes_manifest test {
provider = kubernetes-alpha

manifest = {
Expand Down Expand Up @@ -140,20 +137,16 @@ resource "kubernetes_manifest" "test" {

The `manifest` attribute of the `kubernetes_manifest` resource accepts any arbitrary Kubernetes API object, using Terraform's [map](https://www.terraform.io/docs/configuration/expressions.html#map) syntax. If you have YAML you want to use with this provider, we recommend that you convert it to a map as an initial step and then manage that resource in Terraform, rather than using `yamldecode()` inside the resource block.

You can quickly convert a single YAML file to an HCL map using this one liner:
You can quickly convert a single document YAML file to an HCL map using this one liner:

```
echo 'yamldecode(file("test.yaml"))' | terraform console
echo 'yamldecode(file("input.yaml"))' | terraform console
```

Alternatively, there is also an experimental command line tool [tfk8s](https://github.com/jrhouston/tfk8s) you could use to convert Kubernetes YAML manifests into complete Terraform configurations.
There is also a command line tool [tfk8s](https://github.com/jrhouston/tfk8s) you can use to convert multi-document Kubernetes YAML manifests into complete Terraform configurations.

## Contributing

We welcome your contribution. Please understand that the experimental nature of this repository means that contributing code may be a bit of a moving target. If you have an idea for an enhancement or bug fix, and want to take on the work yourself, please first [create an issue](https://github.com/hashicorp/terraform-provider-kubernetes-alpha/issues/new/choose) so that we can discuss the implementation with you before you proceed with the work.

You can review our [contribution guide](https://github.com/hashicorp/terraform-provider-kubernetes-alpha/blob/master/_about/CONTRIBUTING.md) to begin. You can also check out our [frequently asked questions](https://github.com/hashicorp/terraform-provider-kubernetes-alpha/blob/master/_about/FAQ.md).

## Experimental Status

By using the software in this repository (the "Software"), you acknowledge that: (1) the Software is still in development, may change, and has not been released as a commercial product by HashiCorp and is not currently supported in any way by HashiCorp; (2) the Software is provided on an "as-is" basis, and may include bugs, errors, or other issues; (3) the Software is NOT INTENDED FOR PRODUCTION USE, use of the Software may result in unexpected results, loss of data, or other unexpected results, and HashiCorp disclaims any and all liability resulting from use of the Software; and (4) HashiCorp reserves all rights to make all decisions about the features, functionality and commercial release (or non-release) of the Software, at any time and without any obligation or liability whatsoever.
29 changes: 12 additions & 17 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,11 @@ description: |-

# Kubernetes alpha provider

This Kubernetes provider for Terraform (alpha) supports all API resources in a generic fashion.
This Terraform provider offers a dynamic interface that enables support for any Kubernetes API resource, including Custom Resources.

This provider allows you to describe any Kubernetes resource using HCL. See [Moving from YAML to HCL](#moving-from-yaml-to-hcl) if you have YAML you want to use with the provider.
The provider allows any Kubernetes resource to be codified using HCL. See [Moving from YAML to HCL](#moving-from-yaml-to-hcl) if you have existing YAML you want to use with Terraform.

Please regard this project as experimental. It still requires extensive testing and polishing to mature into production-ready quality. Please [file issues](https://github.com/hashicorp/terraform-provider-kubernetes-alpha/issues/new/choose) generously and detail your experience while using the provider. We welcome your feedback.

Our eventual goal is for this generic resource to become a part of our [official Kubernetes provider](https://github.com/hashicorp/terraform-provider-kubernetes) once it is supported by the Terraform Plugin SDK. However, this work is subject to signficant changes as we iterate towards that level of quality.
This project is currently in beta. Please [file issues](https://github.com/hashicorp/terraform-provider-kubernetes-alpha/issues) generously.

## Schema

Expand Down Expand Up @@ -41,19 +39,19 @@ Our eventual goal is for this generic resource to become a part of our [official
- **command** (String) The plugin executable (absolute path, or expects the plugin to be in OS PATH).
- **env** (Map of String) Environment values to set on the plugin process.

All attributes are optional, but you must either set a config path or static credentials. An empty provider block will not be a functional configuration.
**NOTE:** You must either set a config path (`config_path`) or configure static credentials in the provider block. An empty provider block is not a valid configuration.

Due to the internal design of this provider, access to a responsive API server is required both during PLAN and APPLY. The provider makes calls to the Kubernetes API to retrieve metadata and type information during all stages of Terraform operations.
Due to the internal design of this provider, access to the Kubernetes API server is required both during plan and apply. The provider makes requests to the Kubernetes API to retrieve the OpenAPI type information for each resource, and do dry-runs using [Server-Side Apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/).

### Credentials

For authentication, the provider can be configured with identity credentials sourced from either a `kubeconfig` file, explicit values in the `provider` block, or a combination of both.

If the `config_path` attribute is set to the path of a `kubeconfig` file, the provider will load it and use the credential values in it. When `config_path` is not set **NO EXTERNAL KUBECONFIG WILL BE LOADED**. Specifically, $KUBECONFIG environment variable is **NOT** considered.
If the `config_path` attribute is set to the path of a kubeconfig file, the provider will load it and use the credential values in it. When `config_path` is not set **NO EXTERNAL KUBECONFIG WILL BE LOADED**. Specifically, `KUBECONFIG` environment variable is **NOT** read and the provider does not default to using `~/.kube/config`. This explicitness is to prevent a configuration accidentally being applied to the wrong environment.

Take note of the `current-context` configured in the file. You can override it using the `config_context` provider attribute.
The `current-context` can be overriden by using the `config_context` provider attribute.

If both `kubeconfig` and static credentials are defined in the `provider` block, the provider will prefer any attributes specified by the static credentials and ignore the corresponding attributes in the `kubeconfig`.
If both `config_path` and static credentials are defined in the `provider` block, the provider will prefer any attributes specified by the static credentials and ignore `config_path`.

There are five options for providing identity information to the provider for authentication purposes:

Expand All @@ -63,10 +61,6 @@ There are five options for providing identity information to the provider for au
* a username & password pair
* an authentication plugin, such as `oidc` or `exec` (see examples folder).

## Experimental Status

By using the software in this repository (the "Software"), you acknowledge that: (1) the Software is still in development, may change, and has not been released as a commercial product by HashiCorp and is not currently supported in any way by HashiCorp; (2) the Software is provided on an "as-is" basis, and may include bugs, errors, or other issues; (3) the Software is NOT INTENDED FOR PRODUCTION USE, use of the Software may result in unexpected results, loss of data, or other unexpected results, and HashiCorp disclaims any and all liability resulting from use of the Software; and (4) HashiCorp reserves all rights to make all decisions about the features, functionality and commercial release (or non-release) of the Software, at any time and without any obligation or liability whatsoever.

## Getting Started

If this is your first time here, you can get an overview of the provider by reading our [introductory blog post](https://www.hashicorp.com/blog/deploy-any-resource-with-the-new-kubernetes-provider-for-hashicorp-terraform/).
Expand Down Expand Up @@ -179,13 +173,14 @@ resource "kubernetes_manifest" "test" {

The `manifest` attribute of the `kubernetes_manifest` resource accepts any arbitrary Kubernetes API object, using Terraform's [map](https://www.terraform.io/docs/configuration/expressions.html#map) syntax. If you have YAML you want to use with this provider, we recommend that you convert it to a map as an initial step and then manage that resource in Terraform, rather than using `yamldecode()` inside the resource block.

You can quickly convert a single YAML file to an HCL map using this one liner:
You can quickly convert a single document YAML file to an HCL map using this one liner:

```
echo 'yamldecode(file("test.yaml"))' | terraform console
echo 'yamldecode(file("input.yaml"))' | terraform console
```

Alternatively, there is also an experimental command line tool [tfk8s](https://github.com/jrhouston/tfk8s) you could use to convert Kubernetes YAML manifests into complete Terraform configurations.
There is also a command line tool [tfk8s](https://github.com/jrhouston/tfk8s) you can use to convert multi-document Kubernetes YAML manifests into complete Terraform configurations.


## Contributing

Expand Down
3 changes: 1 addition & 2 deletions docs/resources/kubernetes_manifest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,10 @@ description: |-

# Resource `kubernetes_manifest`

Represents one Kubernetes resource as described in the `manifest` attribute. The manifest value is the HCL transcription of a regular Kubernetes YAML manifest. To transcribe an existing manifest from YAML to HCL, we recommend using the Terrafrom built-in function [`yamldecode()`](https://www.terraform.io/docs/configuration/functions/yamldecode.html) or better yet [this purpose-built tool](https://github.com/jrhouston/tfk8s).
Represents one Kubernetes resource as described in the `manifest` attribute. The manifest value is the HCL transcription of a regular Kubernetes YAML manifest. To convert an existing manifest from YAML to HCL, we recommend using the Terrafrom built-in function [`yamldecode()`](https://www.terraform.io/docs/configuration/functions/yamldecode.html) or [this conversion tool](https://github.com/jrhouston/tfk8s).
Copy link

@sftim sftim Jun 25, 2021

Choose a reason for hiding this comment

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

(nit) I'd write:

Suggested change
Represents one Kubernetes resource as described in the `manifest` attribute. The manifest value is the HCL transcription of a regular Kubernetes YAML manifest. To convert an existing manifest from YAML to HCL, we recommend using the Terrafrom built-in function [`yamldecode()`](https://www.terraform.io/docs/configuration/functions/yamldecode.html) or [this conversion tool](https://github.com/jrhouston/tfk8s).
Represents one Kubernetes resource as described in the `manifest` attribute. The manifest value is the HCL transcription of a regular Kubernetes YAML manifest. To convert an existing manifest from YAML to HCL, we recommend using the Terrafrom built-in function [`yamldecode()`](https://www.terraform.io/docs/configuration/functions/yamldecode.html) or the [`tfk8s`](https://github.com/jrhouston/tfk8s) conversion tool.


Once applied, the `object` attribute reflects the state of the resource as returned by the Kubernetes API, including all default values.


## Schema

### Required
Expand Down
10 changes: 5 additions & 5 deletions docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,19 +20,19 @@ The provider accepts the following configuration attributes under the `provider`
* `env` - (map string to string) Environment values to set on the plugin process.
* `args` - (list of strings) Command line arguments to the plugin command.

All attributes are optional, but you must either set a config path or static credentials. An empty provider block will not be a functional configuration.
**NOTE:** You must either set a config path (`config_path`) or configure static credentials in the provider block. An empty provider block is not a valid configuration.

Due to the internal design of this provider, access to a responsive API server is required both during PLAN and APPLY. The provider makes calls to the Kubernetes API to retrieve metadata and type information during all stages of Terraform operations.
Due to the internal design of this provider, access to the Kubernetes API server is required both during plan and apply. The provider makes requests to the Kubernetes API to retrieve the OpenAPI type information for each resource, and do dry-runs using [Server-Side Apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/).

### Credentials

For authentication, the provider can be configured with identity credentials sourced from either a `kubeconfig` file, explicit values in the `provider` block, or a combination of both.

If the `config_path` attribute is set to the path of a `kubeconfig` file, the provider will load it and use the credential values in it. When `config_path` is not set **NO EXTERNAL KUBECONFIG WILL BE LOADED**. Specifically, $KUBECONFIG environment variable is **NOT** considered.
If the `config_path` attribute is set to the path of a kubeconfig file, the provider will load it and use the credential values in it. When `config_path` is not set **NO EXTERNAL KUBECONFIG WILL BE LOADED**. Specifically, `KUBECONFIG` environment variable is **NOT** read and the provider does not default to using `~/.kube/config`. This explicitness is to prevent a configuration accidentally being applied to the wrong environment.

Take note of the `current-context` configured in the file. You can override it using the `config_context` provider attribute.
The `current-context` can be overriden by using the `config_context` provider attribute.

If both `kubeconfig` and static credentials are defined in the `provider` block, the provider will prefer any attributes specified by the static credentials and ignore the corresponding attributes in the `kubeconfig`.
If both `config_path` and static credentials are defined in the `provider` block, the provider will prefer any attributes specified by the static credentials and ignore `config_path`.

There are five options for providing identity information to the provider for authentication purposes:

Expand Down