Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bazelbuild/rules_k8s

This repository contains rules for interacting with Kubernetes configurations / clusters.
https://github.com/bazelbuild/rules_k8s

bazel bazel-rules docker docker-image k8s kubernetes kubernetes-deployment

Last synced: 2 months ago
JSON representation

This repository contains rules for interacting with Kubernetes configurations / clusters.

Host: GitHub
URL: https://github.com/bazelbuild/rules_k8s
Owner: bazelbuild
License: apache-2.0
Archived: true
Created: 2017-08-29T16:05:44.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2023-05-12T13:44:37.000Z (over 1 year ago)
Last Synced: 2024-07-31T07:18:42.439Z (5 months ago)
Topics: bazel, bazel-rules, docker, docker-image, k8s, kubernetes, kubernetes-deployment
Language: Starlark
Homepage:
Size: 776 KB
Stars: 289
Watchers: 12
Forks: 136
Open Issues: 82
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Authors: AUTHORS

Awesome Lists containing this project

awesome - rules_k8s - This repository contains rules for interacting with Kubernetes configurations / clusters. (Python)

README

# (ARCHIVED) Bazel Kubernetes Rules

**This repository is no longer maintained.**

Prow | Bazel CI
:---: | :---:
[![Build status](https://prow.k8s.io/badge.svg?jobs=pull-rules-k8s-*)](https://prow.k8s.io/?repo=bazelbuild%2Frules_k8s) | [![Build status](https://badge.buildkite.com/4eafd3b619b9febae679bac4ce75b6b74643d48384e7f36eeb.svg)](https://buildkite.com/bazel/k8s-rules-k8s-postsubmit)

## Rules

* [k8s_defaults](#k8s_defaults)
* [k8s_object](#k8s_object)
* [k8s_objects](#k8s_objects)

## Overview

This repository contains rules for interacting with Kubernetes
configurations / clusters.

## Setup

Add the following to your `WORKSPACE` file to add the necessary external dependencies:

* Info for [rules_docker](https://github.com/bazelbuild/rules_docker/#setup)

```python
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

# https://github.com/bazelbuild/rules_docker/#setup
# http_archive("io_bazel_rules_docker", ...)

http_archive(
name = "io_bazel_rules_k8s",
strip_prefix = "rules_k8s-0.5",
urls = ["https://github.com/bazelbuild/rules_k8s/archive/v0.5.tar.gz"],
sha256 = "773aa45f2421a66c8aa651b8cecb8ea51db91799a405bd7b913d77052ac7261a",
)

load("@io_bazel_rules_k8s//k8s:k8s.bzl", "k8s_repositories")

k8s_repositories()

load("@io_bazel_rules_k8s//k8s:k8s_go_deps.bzl", k8s_go_deps = "deps")

k8s_go_deps()
```

## Kubernetes Authentication

As is somewhat standard for Bazel, the expectation is that the
`kubectl` toolchain is preconfigured to authenticate with any clusters
you might interact with.

For more information on how to configure `kubectl` authentication, see the
Kubernetes [documentation](https://kubernetes.io/docs/admin/authentication/).

*NOTE: we are currently experimenting with toolchain features in these rules
so there will be changes upcoming to how this configuration is performed*

### Container Engine Authentication

For Google Container Engine (GKE), the `gcloud` CLI provides a [simple
command](https://cloud.google.com/sdk/gcloud/reference/container/clusters/get-credentials)
for setting up authentication:
```shell
gcloud container clusters get-credentials
```

*NOTE: we are currently experimenting with toolchain features in these rules
so there will be changes upcoming to how this configuration is performed*

## Dependencies

*New: Starting https://github.com/bazelbuild/rules_k8s/commit/ff2cbf09ae1f0a9c7ebdfc1fa337044158a7f57b*

These rules can either use a pre-installed `kubectl` tool (default) or
build the `kubectl` tool from sources.

The `kubectl` tool is used when executing the `run` action from bazel.

The `kubectl` tool is configured via a toolchain rule. Read more about
the kubectl toolchain [here](toolchains/kubectl#kubectl-toolchain).

If GKE is used, also the `gcloud` sdk needs to be installed.

*NOTE: we are currently experimenting with toolchain features in these rules
so there will be changes upcoming to how this configuration is performed*

## Examples

### Basic "deployment" objects

```python
load("@io_bazel_rules_k8s//k8s:object.bzl", "k8s_object")

k8s_object(
name = "dev",
kind = "deployment",

# A template of a Kubernetes Deployment object yaml.
template = ":deployment.yaml",

# An optional collection of docker_build images to publish
# when this target is bazel run. The digest of the published
# image is substituted as a part of the resolution process.
images = {
"gcr.io/rules_k8s/server:dev": "//server:image"
},
)
```

### Aliasing (e.g. `k8s_deploy`)

In your `WORKSPACE` you can set up aliases for a more readable short-hand:
```python
load("@io_bazel_rules_k8s//k8s:k8s.bzl", "k8s_defaults")

k8s_defaults(
# This becomes the name of the @repository and the rule
# you will import in your BUILD files.
name = "k8s_deploy",
kind = "deployment",
# This is the name of the cluster as it appears in:
# kubectl config view --minify -o=jsonpath='{.contexts[0].context.cluster}'
cluster = "my-gke-cluster",
)
```

Then in place of the above, you can use the following in your `BUILD` file:

```python
load("@k8s_deploy//:defaults.bzl", "k8s_deploy")

k8s_deploy(
name = "dev",
template = ":deployment.yaml",
images = {
"gcr.io/rules_k8s/server:dev": "//server:image"
},
)
```

Note that in `load("@k8s_deploy//:defaults.bzl", "k8s_deploy")` both `k8s_deploy`'s are references to the `name` parameter passed to `k8s_defaults`. If you change `name = "k8s_deploy"` to something else, you will need to change the `load` statement in both places.

### Multi-Object Actions

It is common practice in the Kubernetes world to have multiple objects that
comprise an application. There are two main ways that we support interacting
with these kinds of objects.

The first is to simply use a template file that contains your N objects
delimited with `---`, and omitting `kind="..."`.

The second is through the use of `k8s_objects`, which aggregates N `k8s_object`
rules:
```python
# Note the plurality of "objects" here.
load("@io_bazel_rules_k8s//k8s:objects.bzl", "k8s_objects")

k8s_objects(
name = "deployments",
objects = [
":foo-deployment",
":bar-deployment",
":baz-deployment",
]
)

k8s_objects(
name = "services",
objects = [
":foo-service",
":bar-service",
":baz-service",
]
)

# These rules can be nested
k8s_objects(
name = "everything",
objects = [
":deployments",
":services",
":configmaps",
":ingress",
]
)
```

This can be useful when you want to be able to stand up a full environment,
which includes resources that are expensive to recreate (e.g. LoadBalancer),
but still want to be able to quickly iterate on parts of your application.

### Developer Environments

A common practice to avoid clobbering other users is to do your development
against an isolated environment. Two practices are fairly common-place.
1. Individual development clusters
1. Development "namespaces"

To support these scenarios, the rules support using "stamping" variables to
customize these arguments to `k8s_defaults` or `k8s_object`.

For per-developer clusters, you might use:
```python
k8s_defaults(
name = "k8s_dev_deploy",
kind = "deployment",
cluster = "gke_dev-proj_us-central5-z_{BUILD_USER}",
)
```

For per-developer namespaces, you might use:
```python
k8s_defaults(
name = "k8s_dev_deploy",
kind = "deployment",
cluster = "shared-cluster",
namespace = "{BUILD_USER}",
)
```

You can customize the stamp variables that are available at a repository level
by leveraging `--workspace_status_command`. One pattern for this is to check in
the following:
```shell
$ cat .bazelrc
build --workspace_status_command="bash ./print-workspace-status.sh"

$ cat print-workspace-status.sh
cat <
## k8s_object

```python
k8s_object(name, kind, template)
```

A rule for interacting with Kubernetes objects.

Attributes

name

Name, required

Unique name for this rule.

kind

Kind, required

The kind of the Kubernetes object in the yaml.

If this is omitted, the apply, create, replace, delete, describe actions will not exist.

cluster

string, optional

The name of the cluster to which create, replace, delete, describe should speak. Subject to "Make" variable substitution.

If this is omitted, the apply, create, replace, delete, describe actions will not exist.

context

string, optional

The name of a kubeconfig context to use. Subject to "Make" variable
substitution.

If this is omitted, the current context will be used.

namespace

string, optional

The namespace on the cluster within which the actions are
performed. Subject to "Make" variable substitution.

If this is omitted, it will default to the value specified
in the template or if also unspecified there, to the value
"default".

user

string, optional

The user to authenticate to the cluster as configured with kubectl.
Subject to "Make" variable substitution.

If this is omitted, kubectl will authenticate as the user from the
current context.

kubeconfig

kubeconfig file, optional

The kubeconfig file to pass to the `kubectl` tool via the
`--kubeconfig` option. Can be useful if the `kubeconfig` is generated
by another target.

substitutions

string_dict, optional

Substitutions to make when expanding the template.

Follows the same rules as
expand_template
Values are "make variable substituted."
You can also use the Bazel command line option --define
to define your own custom variables.


  # Example

  k8s_object(

    name = "my_ingress",

    kind = "ingress",

    # A template of a Kubernetes ingress object yaml.

    template = ":ingress.yaml",

    # An optional collection of docker_build images to publish

    # when this target is bazel run.  The digest of the published

    # image is substituted as a part of the resolution process.

    substitutions = {

      "%{expand_template_variable}": "$(make_expanded_variable}",

    })

Which is then invoked with bazel run --define make_expanded_variable=value :target
and will replace any occurrences of the literal token %{expand_template_variable} in your
template with the value "value" by way of first make variable
substitution and then string replacement.

Any stamp variables are also replaced with their values. This is done
after make variable substitution.

template

yaml or json file; required

The yaml or json for a Kubernetes object.

images

string to label dictionary

When this target is bazel run the images
referenced by label will be published to the tag key.

The published digests of these images will be substituted
directly, so as to avoid a race in the resolution process

Subject to "Make" variable substitution

image_chroot

string, optional

The repository under which to actually publish Docker images.

resolver

target, optional

A build target for the binary that's called to resolves references
inside the Kubernetes YAML files.

args

string_list, optional

Additional arguments to pass to the kubectl command at execution.

NOTE: You can also pass args via the cli by run something like:
bazel run some_target -- some_args

NOTE: Not all options are available for all kubectl commands. To view the list of global options run: kubectl options

resolver_args

string_list, optional

Additional arguments to pass to the resolver directly.

NOTE: This option is to pass the specific arguments to the resolver directly, such as --allow_unused_images.

## k8s_objects

```python
k8s_objects(name, objects)
```

A rule for interacting with multiple Kubernetes objects.

Attributes

name

Name, required

Unique name for this rule.

objects

Label list or dict; required

The list of objects on which actions are taken.

When bazel run this target resolves each of the object
targets which includes publishing their associated images, and will
print a --- delimited yaml.

If a dict is provided it will be converted to a select statement.

## k8s_defaults

```python
k8s_defaults(name, kind)
```

A repository rule that allows users to alias `k8s_object` with default values.

Attributes

name

Name, required

The name of the repository that this rule will create.

Also the name of rule imported from
@name//:defaults.bzl

kind

Kind, optional

The kind of objects the alias of k8s_object handles.

cluster

string, optional

The name of the cluster to which create, replace, delete, describe should speak.

This should match the cluster name as it would appear in
kubectl config view --minify -o=jsonpath='{.contexts[0].context.cluster}'

context

string, optional

The name of a kubeconfig context to use.

namespace

string, optional

The namespace on the cluster within which the actions are
performed.

user

string, optional

The user to authenticate to the cluster as configured with kubectl.

image_chroot

string, optional

The repository under which to actually publish Docker images.

resolver

target, optional

A build target for the binary that's called to resolves references
inside the Kubernetes YAML files.

## Testing

To test rules_k8s, you can run the provided e2e tests locally on Linux by
following these [instructions](examples/#running-rules_k8s-e2e-tests-locally).

## Support

Users find on stackoverflow, slack and Google Group mailing list.

### Stackoverflow

Stackoverflow is a great place for developers to help each other.

Search through [existing questions] to see if someone else has had the same issue as you.

If you have a new question, please [ask] the stackoverflow community. Include `rules_k8s` in the title and add `[bazel]` and `[kubernetes]` tags.

### Google group mailing list

The general [bazel support] options links to the official [bazel-discuss] Google group mailing list.

### Slack and IRC

Slack and IRC are great places for developers to chat with each other.

There is a `#bazel` channel in the kubernetes slack. Visit the [kubernetes community] page to find the [slack.k8s.io] invitation link.

There is also a `#bazel` channel on [Freenode IRC], although we have found the slack channel more engaging.

[Freenode IRC]: https://freenode.net/
[bazel support]: https://bazel.build/support.html
[bazel-discuss]: https://groups.google.com/forum/#!forum/bazel-discuss
[existing questions]: https://stackoverflow.com/search?q=rules_k8s
[kubernetes community]: https://kubernetes.io/community/
[slack.k8s.io]: http://slack.k8s.io/

## Adopters
Here's a (non-exhaustive) list of companies that use `rules_k8s` in production. Don't see yours? [You can add it in a PR!](https://github.com/bazelbuild/rules_k8s/edit/master/README.md)
* [Etsy](https://www.etsy.com)
* [Jetstack](https://www.jetstack.io/)
* [Prow](https://github.com/kubernetes/test-infra/tree/master/prow)
* [Tink](https://tink.com/)
* [Cookies](https://cookies.co/)