Contribution

• 1: Contributing
• 2: Issues and pull requests migration
• 3: Release Versioning
• 4: Security Policy

1 - Contributing

Thanks for taking the time to join our community and start contributing!

The Contributor Guide provides detailed instructions on how to get your ideas and bug fixes seen and accepted.

Please remember to sign the CNCF CLA and read and observe the Code of Conduct.

2 - Issues and pull requests migration

NOTE This page only applies after Azure cloud provider implementation code has been moved to this repository.

There are some ongoing issues and pull requests addressing the Azure cloud provider in Kubernetes repository.

When we turned to use the standalone cloud provider in this repository, those issues and pull requests should also be moved.

Here are some notes for issues and pull requests migration.

Issue migration

If issue applies only to Azure cloud provider, please close it and create a new one in this repository.

If issue also involves other component, leave it there, but do create a new issue in this repository to track counterpater in Azure cloud provider.

In both cases, leave a link to the new created issue in the old issue.

Pull request migration

Basically we have migrated code from k8s.io/legacy-cloud-providers/azure/ to github.com/sigs.k8s.io/cloud-provider-azure/pkg/provider.

The following steps describe how to port an existing PR from kubernetes repository to this repository.

1. Generate pull request patch

In your kubernetes repository, run following to generate a patch for your PR.

• PR_ID: Pull Request ID in kubernetes repository
• UPSTREAM_BRANCH: Branch name pointing to upstream, basically the branch with url https://github.com/kubernetes/kubernetes.git or https://k8s.io/kubernetes

PR_ID=
UPSTREAM_BRANCH=origin
PR_BRANCH_LOCAL=PR$PR_ID

git fetch $UPSTREAM_BRANCH pull/$PR_ID/head:$PR_BRANCH_LOCAL
MERGE_BASE=$(git merge-base $UPSTREAM_BRANCH/master $PR_BRANCH_LOCAL)
PATCH_FILE=/tmp/${PR_ID}.patch
git diff $MERGE_BASE $PR_BRANCH_LOCAL > $PATCH_FILE
git branch -D $PR_BRANCH_LOCAL

2. Transform the patch and apply

Switch to kubernetes-azure-cloud-controller-manager repo. Apply the patch:

hack/transform-patch.pl $PATCH_FILE | git apply

If any of file in the patch does not fall under Azure cloud provider directory, the transform script will prompt a warning.

3 - Release Versioning

Release source

There are two major code change sources for this project, either may push forward a new release for Kubernetes azure-cloud-controller-manager:

1. Changes in Kubernetes cloud-controller-manager, which happens in Kubernetes repository Since this project dependes on Kubernetes cloud-controller-manager, we’ll periodically sync changes from Kubernetes upstream repository. When upstream shipped a new release tag, we may consider publishing a new release

2. Changes in Azure cloud provider, which happens directly in this repository Azure cloud provider also accepts new features and bug changes. In cases when a security fix is required or when the changes accumulated to certain amount, we may also consider publishing a new release, even if there is no change from Kubernetes upstream.

Versioning

This project is a Kubernetes component whereas the functionalities and APIs all go with Kubernetes upstream project, thus we will use same versioning mechanism of Kubernetes, with some subtle differences for Azure cloud provider and non-Kubernetes changes.

The basic rule is:

1. Every release version follows Semantic Versioning, in the form of MAJOR.MINOR.PATCH
2. For MAJOR.MINOR, it keeps same value as the Kubernetes upstream
3. For PATCH, it is calculated independently:
   • If upstream Kubernetes has a new a patch release, which introduces change in cloud-controller-manager or any component we depend on, then sync the change and increase the PATCH number.
   • If any code change happens in Azure cloud provider or other dependency projects, which becomes eligible for a new release, then increase the PATCH number.

References:

• Kubernetes Release Versioning
• Semantic Versioning

Branch and version scheme

This project uses golang’s vendoring mechanism for managing dependencies (see Dependency management for detail). When talking about ‘sync from Kubernetes upstream’, it actually means vendoring Kubernetes repository code under the vendor directory.

During each sync from upstream, it is usually fine to sync to latest commit. But if there is a new tagged commit in upstream that we haven’t vendored, we should sync to that tagged commit first, and apply a version tag correspondingly if applicable. The version tag mechanism is a bit different on master branch and releasing branch, please see below for detail.

The upstream syncing change should be made in a single Pull Request. If in some case, the upstream change causes a test break, then the pull requests should not be merged until follow up fix commits are added.

For example, if upstream change adds a new cloud provider interface, syncing the upstream change may raise a test break, and we should add the implementation (even no-op) in same pull request.

master branch

This is the main development branch for merging pull requests. When upgrading dependencies, it will sync from Kubernetes upstream’s master branch.

Fixes to releasing branches should be merged in master branch first, and then ported to corresponding release branch.

Version tags:

• X.Y.0-alpha.0
  • This is initial tag for a new release, it will be applied when a release branch is created. See below for detail
• X.Y.0-alpha.W, W > 0
  • Those version tags are periodically created if enough change accumulated. It does not have direct mapping with X.Y.0-alpha.W in Kubernetes upstream

releasing branch

For release X.Y, the branch will have name release-X.Y. When upgrading dependencies, it will sync with Kubernetes upstream’s release-X.Y branch. Release branch would be created when upstream release branch is created and first X.Y.0-beta.0 tag is applied.

Version tags:

• X.Y.0-beta.0
  • X.Y.0-beta.0 would be tagged at first independent commit on release branch, the corresponding separation point commit on master would be tagged X.Y+1.0-alpha.0
  • No new feature changes are allowed from this time on
• X.Y.0-beta.W, W > 0
  • Those version tags are periodically created if enough change accumulated. It does not have direct mapping with X.Y.0-beta.W in Kubernetes upstream
• X.Y.0
  • This is the final release version. When upstream X.Y.0 tag rolls out, we will begin prepare X.Y.0 release
  • After merging upstream X.Y.0 tag commit, we will run full test cycle to ensure the Azure cloud provider works well before release:
    • If any test fails, prepare fixes first. If the fix also applies to master branch, then also apply it to master.
    • Rerun full test cycle till all tests got passed stablely
    • Finally, apply X.Y.0 to latest commit of releasing branch
  • X.Y.1-beta.0 will be tagged at the same commit
• X.Y.Z, Z > 0
  • Those version tags are periodically created if enough change accumulated. It does not have direct mapping with X.Y.Z in Kubernetes upstream
  • Testing and release process follows same rule as X.Y.0

CI and dev version scheme

We use git-describe as versioning source, please check version for detail.

In this case, for commits that does not have a certain tag, the result version would be something like ‘v0.1.0-alpha.0-25-gd7999d10’.

4 - Security Policy

Security Announcements

Join the kubernetes-security-announce group for security and vulnerability announcements.

You can also subscribe to an RSS feed of the above using this link.

Reporting a Vulnerability

Instructions for reporting a vulnerability can be found on the Kubernetes Security and Disclosure Information page.

Supported Versions

Information about supported Kubernetes versions can be found on the Kubernetes version and version skew support policy page on the Kubernetes website.