docs: add getting started w/development guide #667
Conversation
|
Thanks for your pull request. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). 📝 Please follow instructions at https://git.k8s.io/community/CLA.md#the-contributor-license-agreement to sign the CLA. It may take a couple minutes for the CLA signature to be fully registered; after that, please reply here with a new comment and we'll verify. Thanks.
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here. |
k8s-ci-robot
added
the
cncf-cla: no
|
Welcome @adams0619! |
k8s-ci-robot
added
the
size/L
|
/kind documentation |
k8s-ci-robot
added
the
kind/documentation
adams0619
force-pushed
the
dev-guide
branch
2 times, most recently
from
c94cbb5 to
0e09544
Compare
adams0619
force-pushed
the
dev-guide
branch
from
0e09544 to
2c549ec
Compare
k8s-ci-robot
added
cncf-cla: yes
There was a problem hiding this comment.
@adams0619 Thank you for adding this helpful documentation and your first contribution 👍 . I have some feedback provided inline and it is mostly to just simplify the doc by referencing other docs.
docs/developer-guide.md
Outdated
| @@ -0,0 +1,139 @@ | |||
| # Getting Started: Developing on `kubernetes`, `cri-tools`, and `containerd` | |||
There was a problem hiding this comment.
Might read better as: "Developer Getting Started Guide"
docs/developer-guide.md
Outdated
| @@ -0,0 +1,139 @@ | |||
| # Getting Started: Developing on `kubernetes`, `cri-tools`, and `containerd` | |||
|
|
|||
| _**Note**: this documentation was written while running under **`Ubuntu Server 20.04.1 LTS`**_ | |||
There was a problem hiding this comment.
Note sure this disclaimer is necessary as guides in k8s ecosystem are usually pitched at Ubuntu by default.
docs/developer-guide.md
Outdated
|
|
||
| _**Note**: this documentation was written while running under **`Ubuntu Server 20.04.1 LTS`**_ | ||
|
|
||
| ## Pre-requisites / pre-flight checks |
There was a problem hiding this comment.
Header make more sense as just "Pre-requisites"
docs/developer-guide.md
Outdated
| /usr/local/bin/$$critest | ||
| ``` | ||
|
|
||
| Thanks for making it this far in the guide, I hope this guide was helpful and was able to get you up and running, but if you run into any major un-foreseen issues or find errors within this guide then feel free to open an issue or better yet open a PR with a fix; as always, contributions are welcome. |
There was a problem hiding this comment.
Remove this sentence as this is covered in project README
docs/developer-guide.md
Outdated
|
|
||
| --- | ||
|
|
||
| Start w/the following setup guide: | ||
|
|
||
| [Setup-Guide-for-Kubernetes-Developers](https://developer.ibm.com/articles/setup-guide-for-kubernetes-developers/) | ||
|
|
||
| **Skip the `kubernetes` steps from the guide above if you don't plan on doing any development in the `kubernetes` or `crictl` projects.** | ||
|
|
||
| --- | ||
|
|
||
| For the remainder of this guide, we will reference the home directory as `$HOME`. | ||
|
|
||
| After following the setup guide from above, before proceeding ensure you have done the following: | ||
|
|
||
| - You have a `go` directory within your `$HOME` directory and the `go` binary is part of your environments `$PATH` | ||
|
|
||
| ```bash | ||
| $ ls $HOME | ||
| go | ||
|
|
||
| $ env | grep go | ||
| PATH=$PATH:/usr/local/go/bin:$HOME/go/bin # $PATH here refers to truncated version of additional `env` paths that are unrelated this guide / setup | ||
| ``` | ||
|
|
||
| - You have the following dependencies installed: | ||
| - `libseccomp-dev` - _a `libseccomp` development library, required for `containerd`_ | ||
| - `btrfs-tools` - _required by `containerd` for `btrfs` support_ | ||
| - `pkg-config` - _required for linking with `libseccomp`_ | ||
|
|
||
| _For `Ubuntu` these can all be installed using the `apt` package manager_ | ||
|
|
||
| _[Referenced from `cri` repo README](https://github.com/containerd/cri#install-dependencies)_ | ||
|
|
||
| _**Important Note**: `Go` modules follow a similar structure to projects in Github, i.e. when installing and trying to use `cri-tools` as a local module, it should be installed under a folder structure as follows `go/src/github.com/kubernetes-sigs/cri-tools`. `k8s.io` is the only exception which does not follow this structure for legacy reasons._ |
There was a problem hiding this comment.
I think it would be better to compress this down a list of the tools that cri-tools need installed in a system:
e.g.
- Go
- Docker
- Build tools
with a link to the install doc of each
There was a problem hiding this comment.
My reasoning is that better to reference the tools docs as they are more dynamic and open to change. We also have to assume some knowledge of Go. Also the dependencies are for cir in the next section.
docs/developer-guide.md
Outdated
| Make note of where you installed `GO` earlier in the setup process. | ||
|
|
||
| If you followed the guide from the beginning you may likely already have `containerd` installed, but we will need to install the latest development version. | ||
|
|
||
| **Running the development versions of `containerd` is not required if you do not plan on developing for `crictl`, `containerd` or `kubernetes`, you can instead install the latest packaged version for your given OS... for `Ubuntu` run `apt install contianerd`** | ||
|
|
||
| _Keep in mind `cri-o` can also be used in place of `containerd/cri`, but for this guide we will be using `containerd/cri`. You may need some additional steps to ensure `cri-o` works, but the setup should be mostly the same. You can also follow the `cri-o` [install guide](https://github.com/cri-o/cri-o/blob/master/install.md#install-packaged-versions-of-cri-o) if you prefer to use the packaged version._ |
There was a problem hiding this comment.
It might be worth simplifying as follows:
This guide will use containerd/cri as the container runtime. You may use cri-o instead but you may need some additional steps to ensure it works. You can also follow the cri-o install guide if you prefer to use the packaged version.
docs/developer-guide.md
Outdated
| - Clone / Fork the `cri` repo from [https://github.com/containerd/cri](https://github.com/containerd/cri) | ||
|
|
||
| - Pulldown the forked version of `cri` into your `$HOME/go/src/github.com/containerd/cri` and set the `upstream` repo to original project repo url. | ||
| - Note, as mentioned before that the folder you save the repo (`cri`) to locally must follow the same structure as what you see for the repositories path on `github.com` | ||
| - `cd` into your newly cloned `cri` repo on your machine | ||
|
|
||
| ```bash | ||
| $ cd $HOME/go/src/github.com/containerd/cri | ||
| $ | ||
| ``` | ||
|
|
||
| _If you are not running as `root` (which you shouldn't) the commands below may fail on the first try, re-run them by prefixing `sudo` in front to ensure any issues you encounter are not permissions related; example `sudo <command>`_ | ||
|
|
||
| - Install any necessary build tools using `make` | ||
|
|
||
| ```bash | ||
| $ make install.tools | ||
| ``` | ||
|
|
||
| - Install any necessary dependencies using `make` | ||
|
|
||
| ```bash | ||
| $ make install.deps | ||
| ``` | ||
|
|
||
| - Build `containerd` from source and install its binary using `make` | ||
|
|
||
| ```bash | ||
| $ service containerd stop # Stop containerd first, if already running | ||
| $ make && make install | ||
| ``` | ||
|
|
||
| - Run `containerd -v` to validate you are using the development version of `containerd` | ||
|
|
||
| ```bash | ||
| $ containerd -v | ||
| WARN[2020-09-18T21:29:27.616910535Z] This customized containerd is only for CI test, DO NOT use it for distribution. | ||
| containerd github.com/containerd/containerd a536d06c-TEST | ||
| ``` | ||
|
|
||
| - Update the `containerd` config by copying the output from the `containerd config default` command and paste this output to your `containerd` config file which should be located under `/etc/containerd/config.toml` | ||
|
|
||
| ```bash | ||
| $ containerd config default # Remaining output truncated -- copy the output from this command | ||
| WARN[2020-09-18T21:37:38.987970869Z] This customized containerd is only for CI test, DO NOT use it for distribution. | ||
| version = 2 | ||
| root = "/var/lib/containerd" | ||
| state = "/run/containerd" | ||
| ... | ||
| ``` | ||
|
|
||
| _Background for why this is necessary: `docker` makes use of `containerd`, but when installed it has `cri` disabled, the updated config enables `cri` and allows `docker` to make use of the development `containerd/cri` that you have been installing up to this point_ |
There was a problem hiding this comment.
I think this is very valuable information on using containerd/cri. I feel however that it should reside in containerd/cri dev guide. Do you mind opening a PR there and updating its guide where necessary.
I feel in here it should just contain:
Follow the containerd/cri dev guide to make and install containerd/cri runtime.
docs/developer-guide.md
Outdated
| --- | ||
|
|
docs/developer-guide.md
Outdated
|
|
||
| Running `cri-tools` is very similar to the steps followed above | ||
|
|
||
| - Clone / Fork repo into `$HOME/go/src/github.com/kubernetes-sigs/cri-tools` |
There was a problem hiding this comment.
You would assume that someone has the repo by now, so not needed
docs/developer-guide.md
Outdated
| After completing the above steps you should have `go` & `contianerd` binaries installed, `PATH` properly set, and the necessary `go` modules folder setup in your `$HOME` directory. | ||
|
|
||
| Running `cri-tools` is very similar to the steps followed above |
There was a problem hiding this comment.
I think this could be condensed down into:
Build and install cri-tools as follows:
|
Thanks for your pull request. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). 📝 Please follow instructions at https://git.k8s.io/community/CLA.md#the-contributor-license-agreement to sign the CLA. It may take a couple minutes for the CLA signature to be fully registered; after that, please reply here with a new comment and we'll verify. Thanks.
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here. |
k8s-ci-robot
added
cncf-cla: no
k8s-ci-robot
added
cncf-cla: yes
|
@saschagrunert Not sure why the following check ( Error: |
docs/developer-guide.md
Outdated
| `cri-tools` need the following programs installed in a system in order to work correctly: | ||
|
|
||
| - [Go](https://golang.org/doc/install) | ||
| - [Docker](https://docs.docker.com/get-docker/) |
There was a problem hiding this comment.
For which part do we need Docker? I doubt that we require it.
There was a problem hiding this comment.
Agree but worth confirming
docs/developer-guide.md
Outdated
| **Skip the `kubernetes` steps from the guide above if you don't plan on doing any development in the `kubernetes` or `crictl` projects.** | ||
|
|
||
| --- | ||
| `cri-tools` need the following programs installed in a system in order to work correctly: |
There was a problem hiding this comment.
I would rephrase it to mention that we need those for development only.
docs/developer-guide.md
Outdated
|
|
||
| Running the development versions of `containerd` is not required if you do not plan on developing for `crictl`, `containerd` or `kubernetes`, you can instead install the latest packaged version for your given OS... i.e. for `Ubuntu` run `apt install contianerd` | ||
|
|
||
| This guide will use `containerd/cri` as the container runtime. You may use `cri-o` instead but you may need some additional steps to ensure it works. You can also follow the `cri-o` [install guide](https://github.com/cri-o/cri-o/blob/master/install.md#install-packaged-versions-of-cri-o) if you prefer to use the packaged version. |
There was a problem hiding this comment.
| This guide will use `containerd/cri` as the container runtime. You may use `cri-o` instead but you may need some additional steps to ensure it works. You can also follow the `cri-o` [install guide](https://github.com/cri-o/cri-o/blob/master/install.md#install-packaged-versions-of-cri-o) if you prefer to use the packaged version. | |
| This guide will use `containerd/cri` as the container runtime. You may use CRI-O instead but you may need some additional steps to ensure it works. You can also follow the CRI-O [install guide](https://github.com/cri-o/cri-o/blob/master/install.md#install-packaged-versions-of-cri-o) if you prefer to use the packaged version. |
|
Yes the test failures are not coming from this patch, I'll check what's going on. |
|
Looks like a flake, now it's working :) |
docs/developer-guide.md
Outdated
| **Skip the `kubernetes` steps from the guide above if you don't plan on doing any development in the `kubernetes` or `crictl` projects.** | ||
|
|
||
| --- | ||
| `cri-tools` need the following programs installed in a system in order to work correctly: |
docs/developer-guide.md
Outdated
| `cri-tools` need the following programs installed in a system in order to work correctly: | ||
|
|
||
| - [Go](https://golang.org/doc/install) | ||
| - [Docker](https://docs.docker.com/get-docker/) |
There was a problem hiding this comment.
Agree but worth confirming
docs/developer-guide.md
Outdated
| @@ -0,0 +1,66 @@ | |||
| # Developer Getting Started Guide | |||
There was a problem hiding this comment.
Ok, change of mind. I think the most useable title is: "Developer Guide"
docs/developer-guide.md
Outdated
|
|
||
| [Setup-Guide-for-Kubernetes-Developers](https://developer.ibm.com/articles/setup-guide-for-kubernetes-developers/) | ||
|
|
||
| **Skip the `kubernetes` steps from the guide above if you don't plan on doing any development in the `kubernetes` or `crictl` projects.** |
There was a problem hiding this comment.
Remove crictl as it is build in cri-tools.
docs/developer-guide.md
Outdated
|
|
||
| If you followed the guide so far you may likely already have `containerd` installed, but we will need to install the latest development version. | ||
|
|
||
| Running the development versions of `containerd` is not required if you do not plan on developing for `crictl`, `containerd` or `kubernetes`, you can instead install the latest packaged version for your given OS... i.e. for `Ubuntu` run `apt install contianerd` |
There was a problem hiding this comment.
Remove crictl as it is build in cri-tools.
There was a problem hiding this comment.
Not sure this sentence is needed as it seems to conflict with the previous sentence?
docs/developer-guide.md
Outdated
|
|
||
| ## Build & install `containerd/cri` | ||
|
|
||
| If you followed the guide so far you may likely already have `containerd` installed, but we will need to install the latest development version. |
There was a problem hiding this comment.
If you followed the guide so far you may likely already have containerd installed, but we will need to install the latest development version. --> You will require the latest development version of containerd.
docs/developer-guide.md
Outdated
|
|
||
| This guide will use `containerd/cri` as the container runtime. You may use `cri-o` instead but you may need some additional steps to ensure it works. You can also follow the `cri-o` [install guide](https://github.com/cri-o/cri-o/blob/master/install.md#install-packaged-versions-of-cri-o) if you prefer to use the packaged version. | ||
|
|
||
| - Follow the [`containerd/cri` dev guide](https://github.com/containerd/cri#getting-started-for-developers) to `make` and install `containerd/cri` runtime. |
docs/developer-guide.md
Outdated
|
|
||
| ## Build & install `cri-tools` | ||
|
|
||
| You can build and install `cri-tools` following the steps below: |
There was a problem hiding this comment.
You can build and install cri-tools following the steps below: --> You can build and install cri-tools as follows:
docs/developer-guide.md
Outdated
|
|
||
| You can build and install `cri-tools` following the steps below: | ||
|
|
||
| - Install necessary build tools using `make` within the repo directory |
There was a problem hiding this comment.
Install necessary build tools using make within the repo directory --> Install the dependencies:
docs/developer-guide.md
Outdated
| $ make install.tools | ||
| ``` | ||
|
|
||
| - Build `cri-tools` from source and install its binary using `make` |
There was a problem hiding this comment.
Build cri-tools from source and install its binary using make --> Build cri-tools (critest and crictl) and install to common location:
|
Thanks for updating @adams0619. Nearly there, just some more comments inline. |
|
@hickeyma @saschagrunert Updated to address comments... could I get another review on this? |
docs/developer-guide.md
Outdated
|
|
||
| ## Build & install `containerd/cri` | ||
|
|
||
| The latest development version of `containerd` is required. |
There was a problem hiding this comment.
| The latest development version of `containerd` is required. | |
| The latest development version of `containerd` or CRI-O is required. |
k8s-ci-robot
added
the
approved
docs/developer-guide.md
Outdated
|
|
||
| The latest development version of `containerd` is required. | ||
|
|
||
| Running the development versions of `containerd` is not required if you do not plan on developing for `containerd` or `kubernetes`, you can instead install the latest packaged version for your given OS... i.e. for `Ubuntu` run `apt install contianerd` |
There was a problem hiding this comment.
Remove as this is confusing with the sentence before it.
docs/developer-guide.md
Outdated
|
|
||
| This guide will use `containerd/cri` as the container runtime. You may use CRI-O instead but you may need some additional steps to ensure it works. You can also follow the CRI-O [install guide](https://github.com/cri-o/cri-o/blob/master/install.md#install-packaged-versions-of-cri-o) if you prefer to use the packaged version. | ||
|
|
||
| - Follow the [`containerd/cri` dev guide](https://github.com/containerd/cri#getting-started-for-developers) to `make` and install the `containerd/cri` runtime. |
There was a problem hiding this comment.
Remove - because it should not be bulleted.
…ent locally Signed-off-by: Adams Ombonga <Adams.Ombonga@ibm.com>
k8s-ci-robot
added
the
lgtm
|
/approve |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: adams0619, hickeyma, saschagrunert The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
What type of PR is this?
/kind documentation
What this PR does / why we need it:
Adds documentation to help with getting
cri-toolsup and running locally for developmentWhich issue(s) this PR fixes:
None
Special notes for your reviewer:
Does this PR introduce a user-facing change?