Skip to content

Commit

Permalink
Update Makefile documentation and CONTRIBUTING.md
Browse files Browse the repository at this point in the history 
Signed-off-by: Connor Catlett <conncatl@amazon.com>
  • Loading branch information
@ConnorJC3
ConnorJC3 committed Jul 2, 2024
1 parent 9bc14da commit 4d982c6
Show file tree
Hide file tree
Showing 2 changed files with 146 additions and 58 deletions.
114 changes: 82 additions & 32 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,46 +1,96 @@
# Contributing guidelines
# Contributing Guidelines

## Sign the CLA
## Prerequisites

Kubernetes projects require that you sign a Contributor License Agreement (CLA) before we can accept your pull requests. Please see https://git.k8s.io/community/CLA.md for more info

## Contributing A Patch
If you are new to CSI, please go through the [CSI Spec](https://github.com/container-storage-interface/spec/blob/master/spec.md) and [General CSI driver development guideline](https://kubernetes-csi.github.io/docs/developing.html) to get some basic understanding of CSI driver before you start.

1. Submit an issue describing your proposed change to the repo in question.
1. The [repo owners](OWNERS) will respond to your issue promptly.
## Contributing a Patch

1. (Optional, but recommended for large changes) Submit an issue describing your proposed change to the repo in question.
1. If your proposed change is accepted, and you haven't already done so, sign a Contributor License Agreement (see details above).
1. Fork the desired repo, develop and test your code changes.
1. Submit a pull request.
1. Fork the desired repo, develop and test your code changes (see "Development Quickstart Guide" below).
1. When your changes are complete - including tests and documentation if necessary, [submit a pull request](https://github.com/kubernetes-sigs/aws-ebs-csi-driver/compare).
1. Reviewer(s) from the [repo owners](OWNERS) will review your PR. Communicate with your reviewers and address their feedback as required.
1. After merge, your change will typically be included in the next minor release of the EBS CSI Driver and associated Helm chart, which is performed monthly.

## Development Quickstart Guide

This guide demonstrates the basic workflow for developing for the EBS CSI Driver. More detailed documentation of the available `make` targets is available in the [Makefile documentation](docs/makefile.md).

### 1. Local development

If your changes are Helm-only, skip to section 2 (manual testing) below after making your changes.

Run `make` to build a driver binary, and thus discover compiler/syntax errors.

When your change is ready for testing, run `make test` to execute the unit test suite for the driver. If you are making a significant change to the driver (such as a bugfix or new feature), add new unit tests or update existing tests where applicable.

### 2. Cluster setup

When your change is ready to test in a real Kubernetes cluster, create a `kops` cluster to test the driver against:
```bash
make cluster/create
```

If your change affects the Windows implementation of the driver, instead create an `eksctl` cluster with Windows nodes:
```bash
export WINDOWS="true"
# Note: CLUSTER_TYPE must be set for all e2e tests and cluster deletion
# Re-export it if necessary (for example, if running tests in a separate terminal tab)
export CLUSTER_TYPE="eksctl"
make cluster/create
```

Export the `KUBECONFIG` environment variable to access the cluster for manual testing:
```bash
eval "$(make cluster/kubeconfig)"
```

To test a change, build the driver image and then install it:
```bash
make cluster/image
make cluster/install
```

When you are finished manually testing, uninstall the driver:
```bash
make cluster/uninstall
```

### 3. Automated E2E tests

## Development
Please go through [CSI Spec](https://github.com/container-storage-interface/spec/blob/master/spec.md) and [General CSI driver development guideline](https://kubernetes-csi.github.io/docs/developing.html) to get some basic understanding of CSI driver before you start.
Before running any E2E tests, you must create a cluster (see step 2) and build an image if you have not already done so:
```bash
make cluster/image
```

### Requirements
* Golang 1.15.+
* [Ginkgo](https://github.com/onsi/ginkgo) in your PATH for integration testing and end-to-end testing
* Docker 17.05+ for releasing
The driver should not be preinstalled when running E2E tests (the tests will automatically install the driver). If it is, uninstall it first:
```bash
make cluster/uninstall
```

### Dependency
Dependencies are managed through go module. To build the project simply type: `make`
If you are making a change to the driver, the recommended test suite to run is the external tests:
```bash
# Normal external tests (excluding Windows tests)
make e2e/external
# Additionally, run the windows tests if changing Windows behavior
make e2e/external-windows
```

### Testing
* To execute all unit tests, run: `make test`
* To execute sanity test run: `make test-sanity`
* To execute integration tests, run: `make test-integration`
* To execute e2e tests, run: `make test-e2e-single-az` and `make test-e2e-multi-az`
If you are making a change to the Helm chart, the recommended test suite to run is the Helm `ct` tests:
```bash
make e2e/helm-ct
```

### Release Process
Please see [Release Process](./docs/release.md).
After finishing testing, cleanup your cluster :
```bash
make cluster/delete
```

**Notes**:
* Sanity tests make sure the driver complies with the CSI specification
* EC2 instance is required to run integration test, since it is exercising the actual flow of creating EBS volume, attaching it and read/write on the disk. See [Integration Testing](./tests/integration/README.md) for more details.
* E2E tests exercises various driver functionalities in Kubernetes cluster. See [E2E Testing](./tests/e2e/README.md) for more details.
### 4. Before submitting a PR

### Helm and manifests
The Helm chart for this project is in the `charts/aws-ebs-csi-driver` directory. The manifests for this project are in the `deploy/kubernetes` directory. All of the manifests except kustomize patches are generated by running `helm template`. This keeps the Helm chart and the manifests in sync.
Run `make update` to automatically format go source files and re-generate automatically generated files. If `make update` produces any changes, commit them before submitting a PR.

When updating the Helm chart:
* Generate manifests: `make generate-kustomize`
* There are values files in `deploy/kubernetes/values` used for generating some of the manifests
* When adding a new resource template to the Helm chart please update the `generate-kustomize` make target, the `deploy/kubernetes/values` files, and the appropriate kustomization.yaml file(s).
Run `make verify` to run linters and other similar code checking tools. Fix any issues `make verify` discovers before submitting a PR.
90 changes: 64 additions & 26 deletions docs/makefile.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,17 @@ All other tools are downloaded for you at runtime.

This guide demonstrates the basic workflow for developing for the EBS CSI Driver. More detailed documentation of the available `make` targets is available below.

### 1. Local development for the EBS CSI Driver
### 1. Local development

If your changes are Helm-only, skip to section 2 (Run E2E tests) below after making your changes.
If your changes are Helm-only, skip to section 2 (manual testing) below after making your changes.

During development, use `make` at any time to build a driver binary, and thus discover compiler errors. When your change is ready to be tested, run `make test` to execute the unit test suite for the driver. If you are making a significant change to the driver (such as a bugfix or new feature), please add new unit tests or update existing tests where applicable.
Run `make` to build a driver binary, and thus discover compiler/syntax errors.

### 2. Run E2E tests
When your change is ready for testing, run `make test` to execute the unit test suite for the driver. If you are making a significant change to the driver (such as a bugfix or new feature), add new unit tests or update existing tests where applicable.

To create a `kops` cluster to test the driver against:
### 2. Cluster setup

When your change is ready to test in a real Kubernetes cluster, create a `kops` cluster to test the driver against:
```bash
make cluster/create
```
Expand All @@ -42,11 +44,39 @@ export CLUSTER_TYPE="eksctl"
make cluster/create
```

Export the `KUBECONFIG` environment variable to access the cluster for manual testing:
```bash
eval "$(make cluster/kubeconfig)"
```

To test a change, build the driver image and then install it:
```bash
make cluster/image
make cluster/install
```

When you are finished manually testing, uninstall the driver:
```bash
make cluster/uninstall
```

### 3. Automated E2E tests

Before running any E2E tests, you must create a cluster (see step 2) and build an image if you have not already done so:
```bash
make cluster/image
```

The driver should not be preinstalled when running E2E tests (the tests will automatically install the driver). If it is, uninstall it first:
```bash
make cluster/uninstall
```

If you are making a change to the driver, the recommended test suite to run is the external tests:
```bash
# Normal external tests (excluding Windows tests)
make e2e/external
# Instead, if testing Windows
# Additionally, run the windows tests if changing Windows behavior
make e2e/external-windows
```

Expand All @@ -55,46 +85,34 @@ If you are making a change to the Helm chart, the recommended test suite to run
make e2e/helm-ct
```

To cleanup your cluster after finishing testing:
After finishing testing, cleanup your cluster :
```bash
make cluster/delete
```

### 3. Before submitting a PR
### 4. Before submitting a PR

Run `make update` to automatically format go source files and re-generate automatically generated files. If `make update` produces any changes, commit them before submitting a PR.

Run `make verify` to run linters and other similar code checking tools. Fix any issues `make verify` discovers before submitting a PR.

## Building

### `make` or `make bin/aws-ebs-csi-driver` or `make bin/aws-ebs-csi-driver.exe`

Build a binary copy of the EBS CSI Driver for the local platform. This is the default behavior when calling `make` with no target.

The target OS and/or architecture can be overridden via the `OS` and `ARCH` environment variables (for example, `OS=linux ARCH=arm64 make`)

### `make image`
### `make cluster/image`

Build and push a single image of the driver based on the local platform (the same overrides as `make` apply, as well as `OSVERSION` to override container OS version). In most cases, `make all-push` is more suitable. Environment variables are accepted to override the `REGISTRY`, `IMAGE` name, and image `TAG`.

### `make all-push`

Build and push a multi-arch image of the driver based on the OSes in `ALL_OS`, architectures in `ALL_ARCH_linux`/`ALL_ARCH_windows`, and OS versions in `ALL_OSVERSION_linux`/`ALL_OSVERSION_windows`. Also supports `REGISTRY`, `IMAGE`, and `TAG`.

## Local Development

### `make test`

Run all unit tests with race condition checking enabled.
### `make` or `make bin/aws-ebs-csi-driver` or `make bin/aws-ebs-csi-driver.exe`

### `make test/coverage`
Build a binary copy of the EBS CSI Driver for the local platform. This is the default behavior when calling `make` with no target.

Outputs a filtered version of the each package's unit test coverage profiling via go's coverage tool to a local `coverage.html` file.
The target OS and/or architecture can be overridden via the `OS` and `ARCH` environment variables (for example, `OS=linux ARCH=arm64 make`)

### `make test-sanity`
### `make test`

Run the official [CSI sanity tests](https://github.com/kubernetes-csi/csi-test). _Warning: Currently, 3 of the tests are known to fail incorrectly._
Run all unit tests with race condition checking enabled.

### `make verify`

Expand Down Expand Up @@ -198,6 +216,26 @@ eval "$(make cluster/kubeconfig)"

Deletes a cluster created by `make cluster/create`. You must pass the same `CLUSTER_TYPE` and `CLUSTER_NAME` as used when creating the cluster.

### `make cluster/install`

Install the EBS CSI Driver to the cluster via Helm. You must have already run `make cluster/image` to build the image for the cluster, or provide an image of your own.

#### Example: Install the EBS CSI Driver to a cluster for testing

```bash
make cluster/install
```

### `make cluster/uninstall`

Uninstall an installation of the EBS CSI Driver previously installed by `make cluster/install`.

#### Example: Uninstall the EBS CSI Driver

```bash
make cluster/uninstall
```

## E2E Tests

Run E2E tests against a cluster created by `make cluster/create`. You must pass the same `CLUSTER_TYPE` and `CLUSTER_NAME` as used when creating the cluster. You must have already run `make cluster/image` to build the image for the cluster, or provide an image of your own.
Expand Down

0 comments on commit 4d982c6

Please sign in to comment.