Merge branch 'master' into pinned

.github/workflows/e2e.yml

@@ -11,10 +11,10 @@ jobs:
     runs-on: ubuntu-20.04
     timeout-minutes: 240
     steps:
-      - name: Set up Go 1.19
+      - name: Set up Go 1.19.10
         uses: actions/setup-go@v1
         with:
-          go-version: 1.19
+          go-version: 1.19.10
         id: go
 
       - name: Setup Go binary path

.github/workflows/integration.yml

@@ -12,10 +12,10 @@ jobs:
     timeout-minutes: 60
     steps:
 
-      - name: Set up Go 1.19
+      - name: Set up Go 1.19.10
         uses: actions/setup-go@v1
         with:
-          go-version: 1.19
+          go-version: 1.19.10
         id: go
 
       - name: Setup environment

Makefile

@@ -93,3 +93,11 @@ release: static-linux deb rpm cross-arm cross-mac cross-win ## build the release
 	cp $(PACKAGING_DIR)/static/build/mac/cri-dockerd-$(VERSION).tgz $(RELEASE_DIR)/cri-dockerd-$(VERSION).darwin.amd64.tgz
 	# linux
 	cp $(PACKAGING_DIR)/static/build/linux/cri-dockerd-$(VERSION).tgz $(RELEASE_DIR)/cri-dockerd-$(VERSION).amd64.tgz
+
+.PHONY: dev
+dev: cri-dockerd ## Run cri-docker in a running minikube
+	./scripts/replace-in-minikube
+.PHONY: docs
+docs:
+	hugo server --source docs/
+

README.md

@@ -1,3 +1,5 @@
+![docker and kubernetes interact](docs/static/logo.svg)
+
 # cri-dockerd
 
 This adapter provides a shim for [Docker Engine](https://docs.docker.com/engine/)
@@ -10,8 +12,7 @@ For users running `0.2.5` or above, the default network plugin is `cni`. Kuberne
 other network plumbing from upstream as part of the `dockershim` removal/deprecation. In order for a cluster to become
 operational, Calico, Flannel, Weave, or another CNI should be used.
 
-For CI workflows, basic functionality can be provided via [`containernetworking/plugins`](
-https://github.com/containernetworking/plugins).
+For CI workflows, basic functionality can be provided via [`containernetworking/plugins`](https://github.com/containernetworking/plugins).
 
 ## Motivation
 
@@ -29,15 +30,36 @@ tool in [Don't Panic: Kubernetes and Docker](https://blog.k8s.io/2020/12/02/dont
 and on the Mirantis
 [blog](https://www.mirantis.com/blog/mirantis-to-take-over-support-of-kubernetes-dockershim-2/).
 
-## Build and install
+## Using cri-dockerd
+
+### Install
+
+The easiest way to install `cri-dockerd` is to use one of the pre-built binaries or
+packages from the [releases page](https://github.com/Mirantis/cri-dockerd/releases).
+There are numerous supported platforms and using a pre-built package will install
+the binary and setup your system to run it as a service.
+
+Please refer to your platform's documentation for how to install a package for
+additional help with these.
+
+## Advanced Setup
+
+### Installing manually
 
-To begin following the build process for this code, clone this repository in your local environment:
+> Note: the release packages will install to /usr/bin which is reserved for
+> binaries managed by a package manager. Manual installation doesn't involve a
+> package manager and thus uses /usr/local/bin and the service file must be edited
+> to reflect this.
+
+If you would like to install the project manually, you will need to place the binary
+somewhere in your `PATH` and setup a service to run it. The following command is
+a manual install for a Linux system using systemd:
 
 ```shell
 git clone https://github.com/Mirantis/cri-dockerd.git
 ```
 
-The above step creates a local directory called ```cri-dockerd``` which you will need for the following steps.
+The above step creates a local directory called `cri-dockerd` which you will need for the following steps.
 
 To build this code (in a POSIX environment):
 
@@ -69,14 +91,82 @@ install -o root -g root -m 0755 cri-dockerd /usr/local/bin/cri-dockerd
 install packaging/systemd/* /etc/systemd/system
 sed -i -e 's,/usr/bin/cri-dockerd,/usr/local/bin/cri-dockerd,' /etc/systemd/system/cri-docker.service
 systemctl daemon-reload
-systemctl enable cri-docker.service
 systemctl enable --now cri-docker.socket
 ```
 
-## To use with Kubernetes
+### To use with Kubernetes
+
+The default network plugin for `cri-dockerd` is set to `cni` on Linux. There are
+a few ways to change this depending on how you are running the binary.
+
+`--network-plugin=${plugin}` can be passed in as a command line argument when
+ - running the binary directly
+ - adding to `/usr/lib/systemd/system/cri-docker.service` if a service isn't enabled
+ - adding to `/etc/systemd/system/multi-user.target.wants/cri-docker.service` if a service is enabled
+
+Run `systemctl daemon-reload` to restart the service if it was already running.
+
+## Development
+
+### Building
+
+If you would like to build the project yourself, you will need to have Go installed.
+You can find directions for installing the latest version on its website:
+
+[Install the latest version of Go](https://golang.org/doc/install)
+
+Once you have Go installed, you can build the project by running the following command:
+
+```shell
+make cri-dockerd
+```
+
+This will output the binary to the project's root directory as `cri-dockerd`.
+You can then run it directly or install it using the manual process above.
+
+To build for a specific architecture, add `ARCH=` as an argument, where `ARCH`
+is a known build target for Go.
+
+```shell
+ARCH=amd64 make cri-dockerd
+```
+
+### Development Setup
+
+When developing, it is nice to have a separate environment to test in so that
+you don't have to worry about breaking your system. An easy way to do this is
+by setting up a minikube cluster since it uses `cri-dockerd` by default. Follow
+the [minikube installation instructions](https://minikube.sigs.k8s.io/docs/start/)
+to get it installed.
+
+You'll then be able to create a cluster in minikube's VM by running:
+
+```shell
+minikube start
+```
+
+Once the cluster is up, we have a `make` command that will build `cri-dockerd`
+and swap it out for the version running in the cluster. You can run this command
+by running:
+
+```shell
+make dev
+```
+
+## Docs
+
+This folder contains the files used to generate the `cri-dockerd` documentation.
+
+The docs are generated using [Hugo](https://gohugo.io/) and the [Geekdocs](https://themes.gohugo.io/hugo-geekdoc/) theme.
+
+### Editing Docs
+
+The docs can be ran locally with hot-reloading to make editing easier. To do so,
+run the following command in the project's root directory:
+
+```bash
+make docs
+```
 
-The default network plugin for `cri-dockerd` is set to `cni` on Linux. To change this, `--network-plugin=${plugin}`
-can be passed in as a command line argument if invoked manually, or the systemd unit file
-(`/usr/lib/systemd/system/cri-docker.service` if not enabled yet,
-or `/etc/systemd/system/multi-user.target.wants/cri-docker.service` as a symlink if it is enabled) should be
-edited to add this argument, followed by `systemctl daemon-reload` and restarting the service (if running)
+This will launch the development server that is included with Hugo. You can then
+access the docs at http://localhost:1313/

code-of-conduct.md

@@ -0,0 +1,3 @@
+# cri-dockerd Community Code of Conduct
+
+`cri-dockerd` welcomes everyone to be a part of our community. We are an open source project and encourage participation from anyone who is interested in contributing. We are a friendly community and believe in the [CNCF Community Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). Please review it before joining our community.

docs/README.md

@@ -0,0 +1,13 @@
+The docs are generated using [Hugo](https://gohugo.io/) and the [Geekdocs](https://themes.gohugo.io/hugo-geekdoc/) theme.
+
+## How to generate the documentation
+
+The docs can be ran locally with hot-reloading to make editing easier. To do so,
+run the following command in the project's root directory:
+
+```bash
+make docs
+```
+
+This will launch the development server that is included with Hugo. You can then
+access the docs at http://localhost:1313/

docs/archetypes/default.md

@@ -0,0 +1,6 @@
+---
+title: "{{ replace .Name "-" " " | title }}"
+date: {{ .Date }}
+draft: true
+---
+

docs/content/_index.md

@@ -0,0 +1,15 @@
+---
+title: Welcome to cri-dockerd
+geekdocNav: false
+geekdocAlign: center
+---
+
+![docker and kubernetes interact](/images/logo.svg#center)
+
+`cri-dockerd` is an adapter that provides a shim for the [Docker Engine](https://docs.docker.com/engine/)
+that lets you control Docker via the
+Kubernetes [Container Runtime Interface](https://github.com/kubernetes/cri-api#readme).
+
+{{< content "/about/motivation.md" >}}
+
+{{< button size="large" relref="usage/install" >}}Getting Started{{< /button >}}

docs/content/about/_index.md

@@ -0,0 +1,3 @@
+---
+weight: 1
+---

docs/content/about/code-of-conduct.md

@@ -0,0 +1,5 @@
+---
+weight: 4
+---
+
+{{% remote-md "https://api.github.com/repos/Mirantis/cri-dockerd/codes_of_conduct" %}}

docs/content/about/community.md

@@ -0,0 +1,7 @@
+---
+weight: 3
+---
+
+We can be found on the [Kubernetes Slack](https://communityinviter.com/apps/kubernetes/community) in the `#cri-dockerd` channel.
+
+

docs/content/about/documentation.md

@@ -0,0 +1,5 @@
+---
+weight: 3
+---
+
+{{% content "README.md" %}}

docs/content/about/license.md

@@ -0,0 +1,5 @@
+---
+weight: 4
+---
+
+{{% remote-md "https://api.github.com/repos/Mirantis/cri-dockerd/license" %}}

docs/content/about/motivation.md

@@ -0,0 +1,17 @@
+---
+weight: 2
+---
+
+Mirantis and Docker have agreed to partner to maintain the shim code standalone outside Kubernetes, as a conformant CRI
+interface for the Docker Engine API. This means that you can continue to build Kubernetes
+based on the Docker Engine as before, just switching from the built in dockershim to the external one.
+
+Mirantis and Docker intend to work together on making sure it continues to work as well as before and that it
+passes all the conformance tests and continues to work just like the built in version did. Mirantis will be using
+this in Mirantis Kubernetes Engine, and Docker will continue to ship this shim in Docker Desktop. For Mirantis customers,
+this means that Docker Engine’s commercially supported version, Mirantis Container Runtime (MCR), will be CRI compliant.
+
+You can find more information about the context for this
+tool in [Don't Panic: Kubernetes and Docker](https://blog.k8s.io/2020/12/02/dont-panic-kubernetes-and-docker/)
+and on the Mirantis
+[blog](https://www.mirantis.com/blog/mirantis-to-take-over-support-of-kubernetes-dockershim-2/).

docs/content/development/_index.md

@@ -0,0 +1,3 @@
+---
+weight: 3
+---

docs/content/development/building.md

@@ -0,0 +1,24 @@
+---
+weight: 1
+---
+
+If you would like to build the project yourself, you will need to have Go installed.
+You can find directions for installing the latest version on its website:
+
+[Install the latest version of Go](https://golang.org/doc/install)
+
+Once you have Go installed, you can build the project by running the following command:
+
+```shell
+make cri-dockerd
+```
+
+This will output the binary to the project's root directory as `cri-dockerd`.
+You can then run it directly or install it using the manual process above.
+
+To build for a specific architecture, add `ARCH=` as an argument, where `ARCH`
+is a [known build target for Go](https://gist.github.com/asukakenji/f15ba7e588ac42795f421b48b8aede63#goarch-values).
+
+```shell
+ARCH=amd64 make cri-dockerd
+```

docs/content/development/creating-a-release.md

@@ -0,0 +1,21 @@
+---
+weight: 3
+---
+
+These are the steps in order to create a new release for `cri-dockerd`. These steps will need to be done by a project maintainer.
+
+1. Setup the repo for a new release
+    1. Change the version found in `VERSION`, `cmd/version/version.go`, and `packaging/common.mk` to the new version
+    2. Create a PR with these changes and merge them to master
+    3. Build the release artifacts using `make release`
+    4. Verify the artifacts in the `build/release` directory and make sure they look correct
+2. A maintainer creates a new draft release in the project's [releases section](https://github.com/Mirantis/cri-dockerd/releases)
+    1. The name should follow semantic convention prepended with a 'v'
+    2. A tag with the same name should be created on the latest commit to master from the previous step
+    3. Release notes should be generated using the previous tag and the new tag as the range
+    4. Check the box to **Set as a pre-release**
+    5. Upload the release artifacts from the previous step
+    5. Save as a draft
+3. The release can now go through a review process to look for any issues
+4. Change the draft to a published release
+5. Celebrate :cheers:

docs/content/development/development-setup.md

@@ -0,0 +1,23 @@
+---
+weight: 2
+---
+
+When developing, it is nice to have a separate environment to test in so that
+you don't have to worry about breaking your system. An easy way to do this is
+by setting up a minikube cluster since it uses `cri-dockerd` by default. Follow
+the [minikube installation instructions](https://minikube.sigs.k8s.io/docs/start/)
+to get it installed.
+
+You'll then be able to create a cluster in minikube's VM by running:
+
+```shell
+minikube start
+```
+
+Once the cluster is up, we have a `make` command that will build `cri-dockerd`
+and swap it out for the version running in the cluster. You can run this command
+by running:
+
+```shell
+make dev
+```

docs/content/usage/_index.md

@@ -0,0 +1,3 @@
+---
+weight: 2
+---

docs/content/usage/install-manually.md

@@ -0,0 +1,15 @@
+---
+weight: 2
+---
+
+If you would like to install the project manually, you will need to place the binary
+somewhere in your `PATH` and setup a service to run it. The following commands is
+a manual install for a Linux system using systemd:
+
+```shell
+install -o root -g root -m 0755 cri-dockerd /usr/local/bin/cri-dockerd
+install packaging/systemd/* /etc/systemd/system
+sed -i -e 's,/usr/bin/cri-dockerd,/usr/local/bin/cri-dockerd,' /etc/systemd/system/cri-docker.service
+systemctl daemon-reload
+systemctl enable --now cri-docker.socket
+```

docs/content/usage/install.md

@@ -0,0 +1,8 @@
+---
+weight: 1
+---
+
+The easiest way to install `cri-dockerd` is to use one of the pre-built binaries or
+packages from the [releases page](https://github.com/Mirantis/cri-dockerd/releases).
+There are numerous supported platforms and using a pre-built package will install
+the binary and setup your system to run it as a service.