Skip to content

Release management

Publishing a new KubeStellar release#

Prerequisite - make sure you have a GPG signing key#

  1. https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key
  2. https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account
  3. https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key

Create the tags#

Note:#

You currently need write access to the https://github.com/kubestellar/kubestellar repository to perform these tasks.

Checkout the main branch#

git clone git@github.com:kubestellar/kubestellar.git
cd kubestellar
git checkout main

Update the 'kubectl-kubestellar-prep_for_syncer' file with a reference to the new version of the kubestellar syncer version IF you made a new version (and see the syncer doc for how to do that, being careful to not exclude the git commit and cleanliness information from all the tags on the image).#

vi scripts/outer/kubectl-kubestellar-prep_for_syncer

change the version in the following line:

syncer_image="quay.io/kubestellar/syncer:v0.16.0"

Update the core-helm-chart 'Chart.yaml' and 'values.yaml' files with a reference to the new version of the KubeStellar Helm chart version#

vi core-helm-chart/Chart.yaml

change the versions in the 'Chart.yaml' file in the following lines:

...
version: 9
...
appVersion: v0.16.0
...

then in 'values.yaml'

vi core-helm-chart/values.yaml

change the version in the 'values.yaml' file in the following line:

# KubeStellar image parameters
image:
  repository: quay.io/kubestellar/kubestellar
  pullPolicy: IfNotPresent
  tag: release-0.16
...
# Space abstraction layer image parameters
spaceimage:
  repository: quay.io/kubestellar/space-framework
  pullPolicy: IfNotPresent
  tag: release-0.16

Update the VERSION file#

The VERSION file points to the 'latest' and 'stable' release tags associated with the most recent release (latest) and the most stable release (stable). Update the 'stable' and 'latest tags accordingly

vi VERSION

before:

VERSION
...
stable=v0.9.0
latest=v0.15.0
...

after:

VERSION
...
stable=v0.9.0
latest=v0.16.0
...

Update the mkdocs.yml file (pre branch)#

The mkdocs.yml file points to the branch and tag associated with the branch you have checked out. Update the ks_branch and ks_tag key/value pairs at the top of the file

vi docs/mkdocs.yml

before:

mkdocs.yml
...
ks_current_branch: 'release-0.15'
ks_current_tag: 'v0.15.0'
ks_current_helm_version: 8

ks_next_branch: 'release-0.16'
ks_next_tag: 'v0.16.0'
ks_next_helm_version: 9
...

after:

mkdocs.yml
...
ks_current_branch: 'release-0.16'
ks_current_tag: 'v0.16.0'
ks_current_helm_version: 9

ks_next_branch:    # put the branch name of the next numerical branch that will come in the future
ks_next_tag:       # put the tag name of the next numerical tag that will come in the future
ks_next_helm_version: # put the number of the next logical helm version
...

Push the main branch#

git add .
git commit -m "updates to main to support new release v0.16.0"
git push -u origin main

Create a release-major.minor branch#

To create a release branch, identify the current 'release' branches' name (e.g. release-0.16). Increment the or segment as part of the 'release' branches' name. For instance, the 'release' branch is 'main', you might name the new release branch 'release-0.16'.

git checkout -b release-0.16

Update the mkdocs.yml file (post branch)#

The mkdocs.yml file points to the branch and tag associated with the branch you have checked out. Update the ks_branch and ks_tag key/value pairs at the top of the file

vi docs/mkdocs.yml

before:

mkdocs.yml
...
edit_uri: edit/main/docs/content
ks_branch: 'main'
ks_tag: 'latest'
...

after:

mkdocs.yml
...
edit_uri: edit/release-0.16/docs/content
ks_branch: 'release-0.16'
ks_tag: 'v0.16.0'
...

Update the branch name in /README.MD#

There are quite a few references to the main branch /README.MD. They connect the GitHub Actions for the specific branch to the README.MD page. Since we are on the new release branch, its time to update these to point to the release itself.

vi README.MD

before:

https://github.com/kubestellar/kubestellar/actions/workflows/docs-gen-and-push.yml/badge.svg?branch=main

after:

https://github.com/kubestellar/kubestellar/actions/workflows/docs-gen-and-push.yml/badge.svg?branch=release-0.16

Push the new release branch#

git add .
git commit -m "new release version release-0.16"
git push -u origin release-0.16 # replace <major>.<minor> with your incremented <major>.<minor> pair

Remove the current 'stable' alias using 'mike' (DANGER!)#

Be careful, this will cause links to the 'stable' docs, which is the default for our community, to become unavailable. For now, point 'stable' at 'main'

cd docs
mike delete stable # remove the 'stable' alias from the current 'main' branches' doc set
mike deploy --push --rebase --update-aliases main stable # this generates the 'main' branches' docs set and points 'stable' at it temporarily
cd ..

Update the 'stable' alias using 'mike'#

cd docs
mike delete stable # remove the 'stable' alias from the 'main' branches' doc set
git pull
mike deploy --push --rebase --update-aliases release-0.16 stable  # this generates the new 'release-0.16' branches' doc set and points 'stable' at it
cd ..

Test your doc site#

Open a Chrome Incognito browser to https://docs.kubestellar.io and look for the version drop down to be updated to the new release you just pushed with 'git' and deployed with 'mike'

Create a tagged release#

View the existing tags you have for the repo

git fetch --tags
git tag

create a tag that follows ... For this example we will increment tag 'v0.15.0' to 'v0.16.0'

TAG=v0.16.0
REF=release-0.16
git tag --sign --message "$TAG" "$TAG" "$REF"
git push origin --tags

Clean out previous release tar images and the checksums256.txt file from your local build environment#

When you create a build, output goes to your local /build/release. Make sure this path is empty before you start so there is no mixup with your current build.

Create a KubeStellar full build#

./hack/make-release-full.sh v0.16.0

Create a release in GH UI#

  • Navigate to the KubeStellar GitHub Source Repository Releases section at https://github.com/kubestellar/kubestellar/releases
  • Click 'Draft a new release' and select the tag ('v0.16.0')

    • Select the release branch you created above (release-0.16)
    • Add a release title (v0.16.0)
    • Add some release notes ('generate release notes' if you like)
    • select 'pre-release' as a the first step. Once validated the release is working properly, come back and mark as 'release'
    • Attach the binaries that were created in the 'make-release-full' process above
      • You add the KubeStellar-specific '*.tar.gz' and the 'checksums256.txt' files
      • GitHub will automatically add the 'Source Code (zip)' and 'Source Code (tar.gz)'

    Release Example

Create the KubeStellar Core container image#

First, login to quay.io with a user that has credentials to 'write' to the kubestellar quay repo

docker login quay.io

then, remove any running container from moby/buildkit

CONTAINER ID   IMAGE                           COMMAND              
c943925fd137   moby/buildkit:buildx-stable-1   "buildkitd" 

docker rm c943925fd137 -f

and remove the 'buildx' container image from your local docker images

REPOSITORY      TAG               IMAGE ID       CREATED        SIZE
moby/buildkit   buildx-stable-1   16fc6c95ddff   10 days ago    168MB

docker rmi 16fc6c95ddff

finally, make the KubeStellar image from within the local copy of the release branch 'release-0.16'

make kubestellar-image

Create a Space Core build#

pushd space-framework
./make spacecore-image v0.16.0
popd

Update the KubeStellar and Space Core container images just build and uploaded to quay.io#

Head up to quay.io and look for the image of KubeStellar Core container just uploaded. Tag the image with: 'latest', 'release-0.16', and 'v0.16.0' so that helm and other install methods pickup this image.

Update KubeStellar Core Helm repository#

First, make sure you have a version of 'tar' that supports the '--transform' command line option

brew install gnu-tar

then, from root of local copy of https://github.com/kubestellar/kubestellar repo:

gtar -zcf kubestellar-core-9.tar.gz core-helm-chart/ --transform s/core-helm-chart/kubestellar-core/
mv kubestellar-core-9.tar.gz ~
shasum -a 256 ~/kubestellar-core-9.tar.gz
Clone the homebrew-kubestellar repo
git clone git@github.com:kubestellar/helm.git
cd helm
git checkout main

then, from root of local copy of https://github.com/kubestellar/helm repo

mv ~/kubestellar-core-9.tar.gz charts

next, update 'index.yaml' in root of local copy of helm repo (only update the data, not time, on lines 6 and 15):

index.yaml
apiVersion: v1
entries:
  kubestellar-core:
  - apiVersion: v2
    appVersion: v0.16.0
    created: "2023-10-30T12:00:00.727185806-04:00"
    description: A Helm chart for KubeStellar Core deployment as a service
    digest: 6f42d9e850308f8852842cd23d1b03ae5be068440c60b488597e4122809dec1e
    icon: https://raw.githubusercontent.com/kubestellar/kubestellar/main/docs/favicons/favicon.ico
    name: kubestellar
    type: application
    urls:
    - https://helm.kubestellar.io/charts/kubestellar-core-{{ no such element: mkdocs.config.defaults.MkDocsConfig object['ks_new_helm_version'] }}.tar.gz
    version: "9"
generated: "2023-10-30T12:00:00.727185806-04:00"

finally, finally, push to the main branch

git add .
git commit -m "updates to main to support release v0.16.0 of KubeStellar Helm component"
git push -u origin main

Update KubeStellar CLI Brew repository#

Clone the homebrew-kubestellar repo

git clone git@github.com:kubestellar/homebrew-kubestellar.git
cd homebrew-kubestellar
git checkout main

edit the kubestellar_cli.rb file

vi Formula/kubestellar_cli.rb

update all instances of 'url' from v0.15.0 to v0.16.0 (should be 6 of these)

...
    when :arm64
      url "https://github.com/kubestellar/kubestellar/releases/download/v0.16.0/kubestellaruser_v0.16.0_darwin_arm64.tar.gz"
      sha256 "5be4c0b676e8a4f5985d09f2cfe6c473bd2f56ebd3ef4803ca345e6f04d83d6b" 
...

then, update all instances of 'sha256' with the corresponding sha256 hash values in the build/release/checksums256.txt you create during the make-full-release.sh section above. (should be 6 of these)

...
    when :arm64
      url "https://github.com/kubestellar/kubestellar/releases/download/v0.16.0/kubestellaruser_v0.16.0_darwin_arm64.tar.gz"
      sha256 "<corresponding sha256 hash from checksums256.txt>" 
...

finally, push to the main branch

git add .
git commit -m "updates to main to support release v0.16.0 of KubeStellar Brew component"
git push -u origin main

and, to test

brew update
brew install kubestellar-cli

you should see output that indicates an update for the kubestellar brew tap and then an update to version v0.16.0 of the kubestellar_cli brew formula.

Check that GH Workflows for docs are working#

Check to make sure the GitHub workflows for doc generation, doc push, and broken links is working and passing https://github.com/kubestellar/kubestellar/actions/workflows/docs-gen-and-push.yml https://github.com/kubestellar/kubestellar/actions/workflows/broken-links-crawler.yml

Create an email addressed to kubestellar-dev@googlegroups.com and kubestellar-users@googlegroups.com#

Subject: KubeStellar release v0.16.0

Body:

Dear KubeStellar Community,
    Release v0.16.0 is now available at https://github.com/kubestellar/kubestellar/releases/tag/v0.16.0

What's Changed

🐛 Fix display of initial spaces after deploy in kube by @MikeSpreitzer in #1143
✨ Generalize bootstrap wrt namespace in hosting cluster by @MikeSpreitzer in #1144
✨ Generalize bootstrap wrt namespace in hosting cluster by @MikeSpreitzer in #1145
✨ Switch to use k8s code generators by @ezrasilvera in #1139
✨ Bump actions/checkout from 4.1.0 to 4.1.1 by @dependabot in #1151
🌱 Align default core image ref in chart with coming release by @MikeSpreitzer in #1146
📖Update dev-env.md by @francostellari in #1157
📖Update Chart.yaml appVersion by @francostellari in #1158
🐛 Use realpath to see through symlinks by @MikeSpreitzer in #1156
✨ Increase kind version to v0.20 for ubuntu by @fab7 in #1155
📖 Document syncer removal by @MikeSpreitzer in #1164
🌱 Rename urmeta to ksmeta by @MikeSpreitzer in #1166
✨ Make get-internal-kubeconfig fetch mid-level kubeconfig by @MikeSpreitzer in #1161
✨ Make ensure/remove wmw insensitive to current workspace by @MikeSpreitzer in #1160
New Contributors

@fab7 made their first contribution in #1155
Full Changelog: v0.8.0…v0.9.0

Thank you for your continued support,

Andy

Post the same message in the #kubestellar Slack channel#