diff --git a/CHANGELOG.md b/CHANGELOG.md index 97edb9ee..5a758b49 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ All notable changes to this project will be documented in this file. - Added `build_pull_request_ready_for_review` to pipeline resource docs/examples/tests [[PR #396](https://github.com/buildkite/terraform-provider-buildkite/pull/396)] @james2791 - SUP-1370 Update to protocol v6 [[PR #400](https://github.com/buildkite/terraform-provider-buildkite/pull/400)] @jradtilbrook - SUP-1293 Generate docs from code [[PR #397](https://github.com/buildkite/terraform-provider-buildkite/pull/397)] @jradtilbrook +- SUP-1431 Upgrade path for pipeline teams [[PR #401](https://github.com/buildkite/terraform-provider-buildkite/pull/401)] @jradtilbrook The `team` block from the `buildkite_pipeline` resource has been removed. Please use the resource `buildkite_pipeline_team` to create and manage team configuration in a pipeline. diff --git a/buildkite/provider.go b/buildkite/provider.go index b62c27d9..3c4f247a 100644 --- a/buildkite/provider.go +++ b/buildkite/provider.go @@ -8,6 +8,7 @@ import ( "strings" "time" + "github.com/MakeNowJust/heredoc" "github.com/hashicorp/terraform-plugin-framework-timeouts/resource/timeouts" "github.com/hashicorp/terraform-plugin-framework/datasource" "github.com/hashicorp/terraform-plugin-framework/provider" @@ -143,9 +144,11 @@ func (tf *terraformProvider) Resources(context.Context) []func() resource.Resour func (*terraformProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) { resp.Schema = schema.Schema{ - MarkdownDescription: ` - This provider can be used to manage resources on [buildkite.com](https://buildkite.com). - `, + MarkdownDescription: heredoc.Doc(` + ~> You are viewing documentation for a pre-release version of the provider. Please see the latest stable docs at https://registry.terraform.io/providers/buildkite/buildkite/0.26.0/docs + + This provider can be used to manage resources on [buildkite.com](https://buildkite.com). + `), Attributes: map[string]schema.Attribute{ SchemaKeyOrganization: schema.StringAttribute{ Optional: true, diff --git a/docs/guides/upgrade-v1.md b/docs/guides/upgrade-v1.md index 616e813d..af762d6a 100644 --- a/docs/guides/upgrade-v1.md +++ b/docs/guides/upgrade-v1.md @@ -85,6 +85,10 @@ All resources now use their GraphQL IDs as the primary ID in the schema. ## Upgrade Guide +~> If you are coming from a 0.x release of the provider and using `buildkite_pipeline.team` attribute on your resources, +you **must** upgrade to version 0.27.0 prior to upgrading to v1.0. See [Migrate pipeline.team usage to pipeline_team +resource](./upgrade-v1#migrate-pipelineteam-usage-to-pipeline_team-resource) for more info. + ### Pin provider version You should pin your provider installation to the 1.x releases. @@ -100,6 +104,15 @@ terraform { } ``` +### Upgrade provider + +After pinning the provider version, you can upgrade it by running: `terraform init -upgrade`. This will pull in the +latest release under the 1.x version. + +### Refresh state + +The next step is to refresh your state file: `terraform refresh`. + ### Migrate `pipeline.team` usage to `pipeline_team` resource The `team` attribute on the `pipeline` resource was removed in v1.0 in favour of a separate resource: @@ -150,3 +163,43 @@ resource "buildkite_pipeline_team" "deploy_pipeline" { access_level = "BUILD_AND_READ" } ``` + +After applying that change to all `pipeline` resources with a `team` attribute, you can run an apply: `terraform apply`. + +This will show something like below. You can see in the plan that it will temporarily remove the team from the pipeline, +then followup with adding it back through the separate resource. This will result in a very small time window where the +team doesn't have access to the pipeline. It should be unnoticeable. + +``` +Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: + + create + ~ update in-place + +Terraform will perform the following actions: + + # buildkite_pipeline.pipeline will be updated in-place + ~ resource "buildkite_pipeline" "pipeline" { + id = "" + name = "v0.27" + tags = [] + # (10 unchanged attributes hidden) + + - team { + - access_level = "READ_ONLY" -> null + - pipeline_team_id = "" -> null + - slug = "team" -> null + - team_id = "" -> null + } + } + + # buildkite_pipeline_team.p_team will be created + + resource "buildkite_pipeline_team" "p_team" { + + access_level = "READ_ONLY" + + id = (known after apply) + + pipeline_id = "" + + team_id = "" + + uuid = (known after apply) + } + +Plan: 1 to add, 1 to change, 0 to destroy. +``` diff --git a/docs/index.md b/docs/index.md index 685e8935..de43edb1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,11 +3,14 @@ page_title: "buildkite Provider" subcategory: "" description: |- - This provider can be used to manage resources on [buildkite.com](https://buildkite.com). + ~> You are viewing documentation for a pre-release version of the provider. Please see the latest stable docs at https://registry.terraform.io/providers/buildkite/buildkite/0.26.0/docs + This provider can be used to manage resources on buildkite.com https://buildkite.com. --- # buildkite Provider +~> You are viewing documentation for a pre-release version of the provider. Please see the latest stable docs at https://registry.terraform.io/providers/buildkite/buildkite/0.26.0/docs + This provider can be used to manage resources on [buildkite.com](https://buildkite.com). ## Example Usage diff --git a/templates/guides/upgrade-v1.md b/templates/guides/upgrade-v1.md index 616e813d..af762d6a 100644 --- a/templates/guides/upgrade-v1.md +++ b/templates/guides/upgrade-v1.md @@ -85,6 +85,10 @@ All resources now use their GraphQL IDs as the primary ID in the schema. ## Upgrade Guide +~> If you are coming from a 0.x release of the provider and using `buildkite_pipeline.team` attribute on your resources, +you **must** upgrade to version 0.27.0 prior to upgrading to v1.0. See [Migrate pipeline.team usage to pipeline_team +resource](./upgrade-v1#migrate-pipelineteam-usage-to-pipeline_team-resource) for more info. + ### Pin provider version You should pin your provider installation to the 1.x releases. @@ -100,6 +104,15 @@ terraform { } ``` +### Upgrade provider + +After pinning the provider version, you can upgrade it by running: `terraform init -upgrade`. This will pull in the +latest release under the 1.x version. + +### Refresh state + +The next step is to refresh your state file: `terraform refresh`. + ### Migrate `pipeline.team` usage to `pipeline_team` resource The `team` attribute on the `pipeline` resource was removed in v1.0 in favour of a separate resource: @@ -150,3 +163,43 @@ resource "buildkite_pipeline_team" "deploy_pipeline" { access_level = "BUILD_AND_READ" } ``` + +After applying that change to all `pipeline` resources with a `team` attribute, you can run an apply: `terraform apply`. + +This will show something like below. You can see in the plan that it will temporarily remove the team from the pipeline, +then followup with adding it back through the separate resource. This will result in a very small time window where the +team doesn't have access to the pipeline. It should be unnoticeable. + +``` +Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: + + create + ~ update in-place + +Terraform will perform the following actions: + + # buildkite_pipeline.pipeline will be updated in-place + ~ resource "buildkite_pipeline" "pipeline" { + id = "" + name = "v0.27" + tags = [] + # (10 unchanged attributes hidden) + + - team { + - access_level = "READ_ONLY" -> null + - pipeline_team_id = "" -> null + - slug = "team" -> null + - team_id = "" -> null + } + } + + # buildkite_pipeline_team.p_team will be created + + resource "buildkite_pipeline_team" "p_team" { + + access_level = "READ_ONLY" + + id = (known after apply) + + pipeline_id = "" + + team_id = "" + + uuid = (known after apply) + } + +Plan: 1 to add, 1 to change, 0 to destroy. +```