Skip to content
This repository has been archived by the owner on Oct 23, 2024. It is now read-only.

Latest commit

 

History

History
444 lines (330 loc) · 16 KB

DEVELOPMENT.md

File metadata and controls

444 lines (330 loc) · 16 KB
Raw

KUDO Cassandra Operator Development

Table of Contents

Requirements

Walkthrough

Cloning the git repository

Remove the --recurse-submodules flag if you don't have access to the private CI repository. If you do have access to it, also make sure you have GitHub SSH access configured.

git clone \
    --recurse-submodules \
    [email protected]:mesosphere/kudo-cassandra-operator.git \
    /path/to/kudo-cassandra-operator

All commands assume that you're in the project root directory.

cd /path/to/kudo-cassandra-operator

Choosing a name and a namespace for the instance

kudo_cassandra_instance_name="cassandra"
kudo_cassandra_instance_namespace="default"

Creating the namespace (if it doesn't exist)

kubectl create namespace "${kudo_cassandra_instance_namespace}"

Installing the KUDO Cassandra operator

kubectl kudo install ./operator \
        --instance="${kudo_cassandra_instance_name}" \
        --namespace="${kudo_cassandra_instance_namespace}"

Checking out the deploy plan

kubectl kudo plan status \
        --instance="${kudo_cassandra_instance_name}" \
        --namespace="${kudo_cassandra_instance_namespace}"

Checking out the pods

kubectl get pods -n "${kudo_cassandra_instance_namespace}"

Getting the 0th pod name

kudo_cassandra_pod_0="$(kubectl get pods \
                                -o 'jsonpath={.items[0].metadata.name}' \
                                -n "${kudo_cassandra_instance_namespace}")"

Checking out the output of nodetool stats

kubectl exec "${kudo_cassandra_pod_0}" \
        -n "${kudo_cassandra_instance_namespace}" \
        -- \
        bash -c 'nodetool status'

Running a cassandra-stress workload

svc_endpoint="${kudo_cassandra_instance_name}-svc.${kudo_cassandra_instance_namespace}.svc.cluster.local"
kubectl exec "${kudo_cassandra_pod_0}" \
        -n "${kudo_cassandra_instance_namespace}" \
        -- \
        bash -c "cassandra-stress write -node ${svc_endpoint}"

Uninstalling the KUDO Cassandra operator

./scripts/uninstall_operator.sh \
  --instance "${kudo_cassandra_instance_name}" \
  --namespace "${kudo_cassandra_instance_namespace}"

Development

Additional requirements

Compiling templates

The KUDO Cassandra operator makes use of templates so that data that needs to be present in files or available as environment variables in scripts can be centralized in a single place and templated into files or loaded into environment variables in scripts.

The centralized place for that data is the metadata.sh file.

Templates are under the templates directory. The tools/compile_templates.sh script will compile all templates under templates to files in the repository.

note: these scripts currently only run on linux. On other platforms pass the the script through the tools/docker.sh script, for example: ./tools/docker.sh ./tools/compile_templates.sh.

For example, given the following data file:

metadata.sh

export CASSANDRA_VERSION="3.11.5"

Running ./tools/compile_templates.sh will compile

templates/operator/operator.yaml.template

apiVersion: kudo.dev/v1beta1
name: "cassandra"
appVersion: "${CASSANDRA_VERSION}"

into

operator/operator.yaml

apiVersion: kudo.dev/v1beta1
name: "cassandra"
appVersion: "3.11.5"

Assuming also there's a script named cassandra_version.sh that looks like

source "../metadata.sh"
echo "${CASSANDRA_VERSION}"

Running it will output 3.11.5.

$ ./cassandra_version.sh
3.11.5

It's important to notice that changes to templated files have to be done on the template and compiled. For example, changes to operator/operator.yaml have to made in templates/operator/operator.yaml.template and then compiled with tools/compile_templates.sh.

Running static code analyzers

Automatically formatting all files

./tools/format_files.sh

Checking if all files pass formatting and linting checks

./tools/check_files.sh

Building Docker images

./images/build.sh

Running tests

./tests/run.sh <suitename>

Style guide

Opening pull requests

PR titles should be in imperative mood, useful and concise. Example:

Add support for new thing.

PR descriptions should include additional context regarding what is achieved with the PR, why is it needed, rationale regarding decisions that were made, possibly with pointers to actual commits.

Example:

To make it possible for the new thing we had to:
- Prepare this other thing (5417f75)
- Clean up something else (ec4c78d)

This was required because of this and that.

Example output of thing:

    {
      "a": 2
    }


Please look into http://www.somewebsite.com/details-about-thing
for more context.

Merging pull requests

When all checks are green, a PR should be merged as a squash-commit, with its message being the PR title followed by the PR number. Example:

Add support for new thing. (#42)

The description for the squash-commit will ideally be the PR description verbatim. If the PR description was empty (it probably shouldn't have been!) the squash-commit description will by default be a list of all the commits in the PR's branch. That list should be cleaned up to only contain useful entries (no fix, formatting, changed foo, refactored bar), or rewritten so that additional context is added to the commit, like in the example above for PR descriptions.

Releasing

Versioning

The current versioning scheme for the current KUDO Cassandra Operator follows Semantic Versioning 2.0.0. The version is composed of the underlying Apache Cassandra version (app version) concatenated with the operator version. For example, in 3.11.4-0.1.0, 3.11.4 is the Apache Cassandra version and 0.1.0 is the operator version. The operator version is reset on every minor app version release. The current reset target is 0.1.0. Eventually, the reset target will become 1.0.0.

Example hypothetical timeline for releases
Time Apache C* version Operator version KUDO API version Comment Change
T0 3.11.4 0.1.0 v1beta1 Initial release based on Apache C* 3.11.x -
T1 3.11.4 0.1.1 v1beta1 Bug fix in operator-related code Operator patch version bump
T2 3.12.0 0.1.0 v1beta1 Apache C* 3.12.x release Operator version reset
T3 3.11.4 0.2.0 v1beta1 Operator-related feature A added to 3.11.x Operator minor version bump
T3 3.12.0 0.3.0 v1beta1 Operator-related feature A added to 3.12.x Operator minor version bump
T4 4.0.0 0.1.0 v1beta1 Apache C* 4.0.x release Operator version reset
T5 3.11.4 0.3.0 v1beta1 Operator-related feature B added to 3.11.x Operator minor version bump
T5 3.12.0 0.4.0 v1beta1 Operator-related feature B added to 3.12.x Operator minor version bump
T5 4.0.0 0.2.0 v1beta1 Operator-related feature B added to 4.0.x Operator minor version bump
T6 3.11.4 1.0.0 v1 KUDO API version change Operator major version bump
T6 3.12.0 1.0.0 v1 KUDO API version change Operator major version bump
T6 4.0.0 1.0.0 v1 KUDO API version change Operator major version bump

It's important to note that operator versions for different app versions are unrelated. e.g., in the example above both 3.11.4-0.1.0 and 4.0.0-0.1.0 have 0.1.0 as the operator version, but wouldn't necessarily share any commonality with regards to the operator itself. The operator version progression is only meaningful within an app version's major.minor family, i.e. 3.11.x and 4.0.x.

Release workflow

Feature development

Development happens in feature branches. Notable changes should be added to the Unreleased entry in CHANGELOG.md.

Feature branches are merged into the master branch via GitHub PRs.

Updating version and change log

When it is decided that a regular release needs to be done, several things should happen on the master branch first:

  1. Pick and set OPERATOR_VERSION number in metadata.sh according to the versioning scheme
  2. Create an entry for the release in the CHANGELOG. In theory you should just need to add a header and footer with the version number. In practice it might be that some notable changes were not mentioned in the CHANEGELOG.md file, so you should go through the list of commits since the last release and make sure the notable ones are enumerated.

Stable branch creation

The name of stable branch is typically release-vx.y where x.y is the Cassandra major.minor version.

If it does not exist yet, simply create it off master in GitHub web UI using the branch selector widget:

If it exists already, you have two options:

  • if you want to include all changes in master so far (a regular release), then merge master into the stable branch and push manually. Please take care to use a merge commit, do not squash.
  • if you want to do only a patch release with some very specific changes, cherry-pick selected commits onto the stable branch using a regular PR process. In this case, you should also update the version and change log directly on the stable branch, rather than master.

In either case, you need to subsequently make sure the -SNAPSHOT suffix is removed from version strings in the stable branch.

This is achieved by creating and merging a PR against the stable branch where:

  1. value of POSSIBLE_SNAPHOT_SUFFIX in metadata.sh is set to an empty string, and
  2. necessary files are updated by running:
    • ./tools/compile_template.sh
    • ./tools/generate_parameters_markdown.sh
    • ./tools/format_files.sh

Tagging the release

Create a tag for the release, using the GitHub UI. Copy the contents of the release entry from the recently updated changelog.

Building docker images

Docker images need to be built and pushed with names matching the tagged release. This is typically achieved by running the images/build.sh script using TeamCity on the release tag with an additional parameter:

  1. Click the ... next to the Run button on the Docker Push build configuration page.
  2. Select the release tag on the Changes tab:
  3. Add an env.DISABLE_IMAGE_DISAMBIGUATION_SUFFIX environment variable on the Parameters tab:
  4. click Run Build

Copying to the kudobuilder/operators repository

The kudobuilder/operators repository contains a collection of KUDO operators. As of right now (2019-12-11) it is necessary to publish operators there so that packages can be built for installation via kubectl kudo install.

This step can be done automatically with the tools/create_operators_pull_request.py script.

The most convenient way to run it is with the dedicated TeamCity job. Just run it on the tag similarly to how you ran the docker images job.

This will create a PR which needs to be reviewed and approved. See the build log tag for a link.

Building and pushing a KUDO operator package

Ask the friendly folks on #kudo channel on the kubernetes.slack.com instance.

Lather, rinse, repeat as required

Once the stable branch is created, additional commits may be landed on it either via merging from the master branch or cherry-picking individual commits.

These can then be released by repeating this workflow.