From d9c9c742fd5c9180ebd573312cafe8d7c79f0f0e Mon Sep 17 00:00:00 2001 From: joerger Date: Thu, 3 Mar 2022 17:30:30 -0800 Subject: [PATCH 1/5] Create Teleport Plugins release RFD. Add update-api-version and release-version make targets. --- Makefile | 15 ++++- rfd/0002-teleport-plugins-versioning.md | 79 +++++++++++++++++++++++++ 2 files changed, 93 insertions(+), 1 deletion(-) create mode 100644 rfd/0002-teleport-plugins-versioning.md diff --git a/Makefile b/Makefile index 750deed75..c930b1b56 100644 --- a/Makefile +++ b/Makefile @@ -80,8 +80,21 @@ releases: release/access-slack release/access-jira release/access-mattermost rel .PHONY: build-all build-all: access-slack access-jira access-mattermost access-pagerduty access-gitlab access-email terraform event-handler +.PHONY: release-version +release-version: update-api-version update-version terraform/gen-schema update-tag + +.PHONY: +update-api-version: + @test $(VERSION) + # Update the teleport/api dependency to the given version. + # This will fail if teleport/api@VERSION has not been released. + # It can be manually updated to a specific git commit with + # go get github.com/gravitational/telepeport/api@v0.0.0-timestamp-6_byte_hex_commit_hash. + go get github.com/gravitational/telepeport/api@v$(VERSION) + go mod tidy + .PHONY: update-version -update-version: +update-version: update-api-version # Make sure VERSION is set on the command line "make update-version VERSION=x.y.z". @test $(VERSION) sed -i '1s/.*/VERSION=$(VERSION)/' event-handler/Makefile diff --git a/rfd/0002-teleport-plugins-versioning.md b/rfd/0002-teleport-plugins-versioning.md new file mode 100644 index 000000000..e2463318c --- /dev/null +++ b/rfd/0002-teleport-plugins-versioning.md @@ -0,0 +1,79 @@ +--- +authors: Brian Joerger (bjoerger@goteleport.com) +state: draft +--- + +# RFD 2 - Teleport Plugins releases + +## What + +Release strategy for Teleport plugins. + +## Why + +With the release of the Teleport API as a [go module](https://pkg.go.dev/github.com/gravitational/teleport) +and the addition of new plugins (Terraform) which must be updated for every new +version, it's time to layout a proper release process. + +## Details + +Teleport plugins are released in line with Teleport releases. This leads to the +plugins following the same [versioning scheme](https://github.com/gravitational/teleport/blob/master/rfd/0012-teleport-versioning.md#rfd-12---teleport-versioning) +as Teleport, and more importantly, the same [compatibility guidelines](https://github.com/gravitational/teleport/blob/master/rfd/0012-teleport-versioning.md#compatibility). + +These releases are more often than not just vanity releases, with no functional +changes in them. When there are functional changes in a plugin, they must follow +the same compatibility guidelines above. + +### Release process + +The full release process is contained in `make release-version VERSION=vX.Y.Z`. +This will update the version files of each plugin, update the `github/gravitational/teleport/api` +dependency, regenerated the Terraform Schema, and update the git tags. + +Some basic manual changes may need to be made to handle significant changes +made to the Teleport API, as explained below. + +#### Teleport API dependency + +The `github/gravitational/teleport/api` dependency should be updated with every +Teleport Plugins release to ensure compatibility with its corresponding Teleport +version. This can be done with `go get github.com/gravitational/teleport/api@vX.Y.Z`, +which can be added to the `make update-version` target. + +However, this may lead to errors if significant changes have been made to the API, +and will require some manual work to resolve. + +To avoid delaying releases, a PR should be made as soon as `teleport@vX.Y.Z-beta.1` +is released to update the Plugins version to `vX.Y.Z-beta.1`. Any issues can then +be resolved well before `teleport@vX.Y.Z-beta.1` is released, and updated afterwards. + +Alternatively, if we shift towards using release branches (detailed below), then +the beta PR canbe merged into `branch/vX` and then another PR can be made once +`teleport@vX.Y.Z-beta.1` is released. + +#### Terraform Provider + +The Terraform Provider uses `teleport/api/types.proto` directly to generate a +Terraform Schema for Teleport resources. Therefore every time the `teleport/api` +package is upgraded, we must regenerate the Terraform Schema. + +This is handled in two steps: + - Update `terraform/gen_teleport.yaml` + - If any resources have been upgraded (e.g. `RoleV4` -> `RoleV5`), those + changes must be reflected here. Any upgrades needed should be easy to spot + as they can be seen in the linting errors from updating the API dependency. + - Other sections may need to be updated, such as `sensitive fields`. + - Run `make -C terraform gen-schema` + +### Additional Concerns + +#### Release branches + +The teleport-plugins repository only makes releases from `master`. This means +that new features will always go into the next release, and change and fixes +can not be easily back-ported. + +This has not been an issue thus-far, but in the future we can consider adopting +the same [release branches](https://github.com/gravitational/teleport/blob/master/rfd/0012-teleport-versioning.md#git-branches) +strategy as Teleport. \ No newline at end of file From 73829c95e121a974cb2a48b884a366cb4bc33de4 Mon Sep 17 00:00:00 2001 From: joerger Date: Thu, 3 Mar 2022 18:12:08 -0800 Subject: [PATCH 2/5] Add small mention of buf for .proto dependency management. --- rfd/0002-teleport-plugins-versioning.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/rfd/0002-teleport-plugins-versioning.md b/rfd/0002-teleport-plugins-versioning.md index e2463318c..7b6d876bd 100644 --- a/rfd/0002-teleport-plugins-versioning.md +++ b/rfd/0002-teleport-plugins-versioning.md @@ -66,6 +66,10 @@ This is handled in two steps: - Other sections may need to be updated, such as `sensitive fields`. - Run `make -C terraform gen-schema` +In the future, we can consider using [buf](https://docs.buf.build/introduction) +or something similar to handle `.proto` dependencies more carefully, and avoid +the need for unguided manual fixes. + ### Additional Concerns #### Release branches From be55a1527338428ada66ac7be152845f6c71ec38 Mon Sep 17 00:00:00 2001 From: joerger Date: Tue, 8 Mar 2022 10:11:08 -0800 Subject: [PATCH 3/5] Update makefile targets and resolve PR comments. --- Makefile | 12 ++++++++---- ...ioning.md => 0003-teleport-plugins-versioning.md} | 4 ++-- 2 files changed, 10 insertions(+), 6 deletions(-) rename rfd/{0002-teleport-plugins-versioning.md => 0003-teleport-plugins-versioning.md} (96%) diff --git a/Makefile b/Makefile index c930b1b56..d74649ab5 100644 --- a/Makefile +++ b/Makefile @@ -80,10 +80,7 @@ releases: release/access-slack release/access-jira release/access-mattermost rel .PHONY: build-all build-all: access-slack access-jira access-mattermost access-pagerduty access-gitlab access-email terraform event-handler -.PHONY: release-version -release-version: update-api-version update-version terraform/gen-schema update-tag - -.PHONY: +.PHONY: update-api-version update-api-version: @test $(VERSION) # Update the teleport/api dependency to the given version. @@ -93,6 +90,13 @@ update-api-version: go get github.com/gravitational/telepeport/api@v$(VERSION) go mod tidy + # Once the API version is updated, the terraform schema + # must be regenerated with the up to date .proto files. + # If significant changes have been made to the grpc API + # then the terraform/gen_teleport.yaml file will need to + # be updated manually. + $(MAKE) -C terraform gen-schema + .PHONY: update-version update-version: update-api-version # Make sure VERSION is set on the command line "make update-version VERSION=x.y.z". diff --git a/rfd/0002-teleport-plugins-versioning.md b/rfd/0003-teleport-plugins-versioning.md similarity index 96% rename from rfd/0002-teleport-plugins-versioning.md rename to rfd/0003-teleport-plugins-versioning.md index 7b6d876bd..cba9fa98f 100644 --- a/rfd/0002-teleport-plugins-versioning.md +++ b/rfd/0003-teleport-plugins-versioning.md @@ -3,7 +3,7 @@ authors: Brian Joerger (bjoerger@goteleport.com) state: draft --- -# RFD 2 - Teleport Plugins releases +# RFD 3 - Teleport Plugins releases ## What @@ -46,7 +46,7 @@ and will require some manual work to resolve. To avoid delaying releases, a PR should be made as soon as `teleport@vX.Y.Z-beta.1` is released to update the Plugins version to `vX.Y.Z-beta.1`. Any issues can then -be resolved well before `teleport@vX.Y.Z-beta.1` is released, and updated afterwards. +be resolved well before `teleport@vX.Y.Z` is released, and updated afterwards. Alternatively, if we shift towards using release branches (detailed below), then the beta PR canbe merged into `branch/vX` and then another PR can be made once From 2c9be53ff4536bdb799bdd1c9f01ffbb82b2295d Mon Sep 17 00:00:00 2001 From: joerger Date: Wed, 9 Mar 2022 17:18:27 -0800 Subject: [PATCH 4/5] Move update api version to end of update version target, in case of failure due to improper api versioning. --- Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index d74649ab5..50dc754bb 100644 --- a/Makefile +++ b/Makefile @@ -98,7 +98,7 @@ update-api-version: $(MAKE) -C terraform gen-schema .PHONY: update-version -update-version: update-api-version +update-version: # Make sure VERSION is set on the command line "make update-version VERSION=x.y.z". @test $(VERSION) sed -i '1s/.*/VERSION=$(VERSION)/' event-handler/Makefile @@ -114,6 +114,7 @@ update-version: update-api-version sed -i '1s/.*/VERSION=$(VERSION)/' access/email/Makefile make -C access/email version.go sed -i '1s/.*/VERSION=$(VERSION)/' terraform/install.mk + $(MAKE) update-api-version .PHONY: update-tag update-tag: From 4b8c59d7d2cbee1894f1ecc585c7984c33c0090e Mon Sep 17 00:00:00 2001 From: joerger Date: Thu, 9 Jun 2022 12:55:29 -0700 Subject: [PATCH 5/5] Add integration test section. --- rfd/0003-teleport-plugins-versioning.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/rfd/0003-teleport-plugins-versioning.md b/rfd/0003-teleport-plugins-versioning.md index cba9fa98f..9a9acd490 100644 --- a/rfd/0003-teleport-plugins-versioning.md +++ b/rfd/0003-teleport-plugins-versioning.md @@ -70,6 +70,16 @@ In the future, we can consider using [buf](https://docs.buf.build/introduction) or something similar to handle `.proto` dependencies more carefully, and avoid the need for unguided manual fixes. +#### Integration Tests + +The repo's integration tests directly download versions of `teleport`, `tsh`, and `tctl` +to handle integration testing. The version downloaded should be updated at least every +major release or else the tests will fail or fail to fail when something is broken. + +The version referenced by `TELEPORT_GET_VERSION` in the drone and cloudbuild files should +be updated, and the version should be added to `lib/integration/testing/download.go` with +the correct sha256 values. + ### Additional Concerns #### Release branches