From 6eeb67ea73bc6ba277b0840d2ca8ded6d1141e9a Mon Sep 17 00:00:00 2001 From: John Houston Date: Mon, 31 May 2021 18:58:45 -0400 Subject: [PATCH 1/2] Remove experimental language from docs --- README.md | 41 +++++++++++---------------- docs/index.md | 19 +++++-------- docs/resources/kubernetes_manifest.md | 3 +- 3 files changed, 25 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index f6727a47..77047645 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,24 @@ -# Kubernetes provider for Terraform (alpha) +# Kubernetes-alpha provider for Terraform + Terraform logo - - -![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 @@ -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 = { @@ -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 = { @@ -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 = { @@ -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. diff --git a/docs/index.md b/docs/index.md index 6bbbbf7d..6838bf24 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 @@ -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/). @@ -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 diff --git a/docs/resources/kubernetes_manifest.md b/docs/resources/kubernetes_manifest.md index 3560d505..c608f3d3 100644 --- a/docs/resources/kubernetes_manifest.md +++ b/docs/resources/kubernetes_manifest.md @@ -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). Once applied, the `object` attribute reflects the state of the resource as returned by the Kubernetes API, including all default values. - ## Schema ### Required From a899b1f02b7a18c811542c9e0f9f98baf98397db Mon Sep 17 00:00:00 2001 From: John Houston Date: Tue, 15 Jun 2021 01:23:38 -0400 Subject: [PATCH 2/2] Tidy up configuration docs --- docs/index.md | 10 +++++----- docs/usage.md | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/index.md b/docs/index.md index 6838bf24..9064773e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -39,19 +39,19 @@ This project is currently in beta. Please [file issues](https://github.com/hashi - **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: diff --git a/docs/usage.md b/docs/usage.md index be977a36..72225d53 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -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: