diff --git a/docs/src/README.md b/docs/src/README.md index 3bedc7b..3f46439 100644 --- a/docs/src/README.md +++ b/docs/src/README.md @@ -1,4 +1,4 @@ -![lockc](/images/logo-horizontal-lockc.png) +![lockc](https://rancher-sandbox.github.io/lockc/images/logo-horizontal-lockc.png) # Introduction diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 063352a..d7e9649 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -4,20 +4,22 @@ - [Containers do not contain](containers-do-not-contain.md) - [Architecture](architecture.md) - [Getting started](configuration.md) - - [Build](build/README.md) - - [Dapper](build/dapper.md) - - [Cargo](build/cargo.md) - - [Container image](build/container-image.md) - [Install](install/README.md) - [With Docker](install/docker.md) - [With Kubernetes](install/kubernetes.md) - - [Development environment (Terraform)](terraform/README.md) - - [libvirt](terraform/libvirt.md) - - [OpenStack](terraform/openstack.md) - [Policies](policies/README.md) - [File access](policies/file-access.md) - [Mount](policies/mount.md) - [Syslog](policies/syslog.md) - [Tuning](tuning/README.md) +- [For Developers](developers/README.md) + - [Repositories](developers/repositories.md) + - [Build](developers/build/README.md) + - [Dapper](developers/build/dapper.md) + - [Cargo](developers/build/cargo.md) + - [Container image](developers/build/container-image.md) + - [Development environment (Terraform)](developers/terraform/README.md) + - [libvirt](developers/terraform/libvirt.md) + - [OpenStack](developers/terraform/openstack.md) - [Demos](demos/README.md) - [Mount](demos/mount.md) diff --git a/docs/src/developers/README.md b/docs/src/developers/README.md new file mode 100644 index 0000000..c2e25e8 --- /dev/null +++ b/docs/src/developers/README.md @@ -0,0 +1,9 @@ +# For Developers + +- [Repositories] - Cloning and working with our git repositories +- [Build] - How to build lockc from the sources +- [Development environment (Terraform)] - Using Terraform for setting up development environment lockc + +[Repositories]: repositories.md +[Build]: build/README.md +[Development environment (Terraform)]: terraform/README.md diff --git a/docs/src/build/README.md b/docs/src/developers/build/README.md similarity index 100% rename from docs/src/build/README.md rename to docs/src/developers/build/README.md diff --git a/docs/src/build/cargo.md b/docs/src/developers/build/cargo.md similarity index 70% rename from docs/src/build/cargo.md rename to docs/src/developers/build/cargo.md index 9db8695..600900f 100644 --- a/docs/src/build/cargo.md +++ b/docs/src/developers/build/cargo.md @@ -4,7 +4,7 @@ If you are comfortable with installing all dependencies on your host system, you need to install the following software: * LLVM -* libbpf, bpftool +* bpftool * Rust, Cargo ## LLVM @@ -31,58 +31,25 @@ zypper in clang llvm If there is no packaging of recent LLVM versions for your distribution, there is also an option to [download binaries](https://releases.llvm.org/download.html). -## libbpf, bpftool +## bpftool -libbpf is the official C library for writing, loading and managing BPF programs -and entities. bpftool is the official CLI for interacting with BPF subsystem. +bpftool is the official CLI for interacting with BPF subsystem. Distributions with up to date software (Arch, Fedora, openSUSE Tumbleweed) -usually provide packaging for both. +usually provide packaging for it. Especially for more stable and less up to date distributions, but even -generally, we would recommend to build both dependencies from source. Both of +generally, we would recommend to build bpftool from source. Both of them are the part of the Linux kernel source. -The easiest way to get the kernel source is to download a tarball available on -[kernel.org](https://www.kernel.org/). Then build and install tools from it -(the version might vary from this snippet): +bpftool is available in its own repo - [github.com/libbpf/bpftool](https://github.com/libbpf/bpftool). +It lets you to build bpftool with the following commands: ```bash -tar -xvf linux-5.14.9.tar.xz -cd linux-5.14.9 -cd tools/lib/bpf -make -j $(nproc) -make install prefix=/usr -cd ../../bpf/bpftool -make -j $(nproc) -make install prefix=/usr -``` - -If you are interested in tracking the history of Linux kernel source and/or are -comfortable using git for it, you can clone one of the git trees: - -* [stable tree](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/) - - stable releases and release candidates, this is where the tarball comes from -* [mainline tree](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/) - - patches accepted by Linus, release candidates -* [bpf-next tree](https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/) - - development of BPF features, before being mainlined -* [bpf tree](https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf.git/) - - BPF bugfixes which are backported to the stable tree - -Assuming you want to use the stable tree: - -```bash -git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git -cd linux -git tag -l # List available tags -git checkout v5.14.9 # Check out to whatever is the newest -cd tools/lib/bpf -make -j $(nproc) -make install prefix=/usr -cd ../../bpf/bpftool -make -j $(nproc) -make install prefix=/usr +git clone --recurse-submodules https://github.com/libbpf/bpftool.git +cd src +make +sudo make install prefix=/usr ``` ## Installing Rust diff --git a/docs/src/build/container-image.md b/docs/src/developers/build/container-image.md similarity index 100% rename from docs/src/build/container-image.md rename to docs/src/developers/build/container-image.md diff --git a/docs/src/build/dapper.md b/docs/src/developers/build/dapper.md similarity index 100% rename from docs/src/build/dapper.md rename to docs/src/developers/build/dapper.md diff --git a/docs/src/developers/repositories.md b/docs/src/developers/repositories.md new file mode 100644 index 0000000..71be9b5 --- /dev/null +++ b/docs/src/developers/repositories.md @@ -0,0 +1,16 @@ +# Repositories + +lockc currently uses two git repositories: + +* **[rancher-sandbox/lockc](https://github.com/rancher-sandbox/lockc)** - the + main repository containing lockc source code +* **[rancher-sandbox/lockc-helm-charts](https://github.com/rancher-sandbox/lockc-helm-charts)** - + repository with Helm charts to deploy lockc on Kubernetes + +If you are interested in development and contributing to lockc, we recommend to +fork and clone both of them. Both will be needed especially for building a +[development environment based on Terraform](terraform/README.md). + +The latter chapters assume that you have **lockc** and **lockc-helm-charts** +cloned in the same parent directory. For example, as +*$HOME/my-repositories/lockc* and *$HOME/my-repositories/lockc-helm-charts*. diff --git a/docs/src/terraform/README.md b/docs/src/developers/terraform/README.md similarity index 100% rename from docs/src/terraform/README.md rename to docs/src/developers/terraform/README.md diff --git a/docs/src/terraform/libvirt.md b/docs/src/developers/terraform/libvirt.md similarity index 96% rename from docs/src/terraform/libvirt.md rename to docs/src/developers/terraform/libvirt.md index 7285865..3427b5b 100644 --- a/docs/src/terraform/libvirt.md +++ b/docs/src/developers/terraform/libvirt.md @@ -20,7 +20,8 @@ sudo systemctl restart libvirtd ## Running VMs -Now it's time to prepare Terraform environment. +Now it's time to prepare Terraform environment. Terraform files are included in +the main lockc git repository. ```bash cd contrib/terraform/libvirt @@ -130,13 +131,10 @@ kube-system kube-scheduler-lockc-control-plane-0 1/1 Running kube-system kube-scheduler-lockc-control-plane-1 1/1 Running 0 14m ``` -Now it's time to build and deploy lockc! Detailed instructions how to do that -are in the following documentation sections: +Now it's time to build and deploy lockc! -* [Container image](../build/container-image.md) -* [Install on Kubernetes](../install/kubernetes.md) - -But let's continue with a short summary of the easiest way to do that: +To build lockc container image, we have to go to the main directory in lockc +git repository: ```bash # Go to the main directory of lockc sources @@ -144,7 +142,14 @@ cd ../../.. export IMAGE_NAME=$(uuidgen) docker build -t ttl.sh/${IMAGE_NAME}:30m . docker push ttl.sh/${IMAGE_NAME}:30m -helm install lockc contrib/helm/lockc/ --namespace kube-system \ +``` + +Then we need to go to the lockc-helm-charts git repository: + +```bash +# Go to the main directory of lockc-helm-charts sources +cd ../lockc-helm-charts +helm install lockc charts/lockc/ --namespace kube-system \ --set lockcd.image.repository=ttl.sh/${IMAGE_NAME} \ --set lockcd.image.tag=30m \ --set lockcd.debug.enabled=true diff --git a/docs/src/terraform/openstack.md b/docs/src/developers/terraform/openstack.md similarity index 100% rename from docs/src/terraform/openstack.md rename to docs/src/developers/terraform/openstack.md diff --git a/docs/src/install/README.md b/docs/src/install/README.md index 55af1c5..bdc9d71 100644 --- a/docs/src/install/README.md +++ b/docs/src/install/README.md @@ -1 +1,12 @@ # Install + +lockc provides integration with two container engines and separate installation +methods for each of them: + +* **[Kubernetes]** (+ containerd-cri) - installation through a Helm chart, + after which lockc secures newly created pods +* **[Docker]** - installation on a single machine with Docker as a loca + container engine + +[Kubernetes]: kubernetes.md +[Docker]: docker.md diff --git a/docs/src/install/kubernetes.md b/docs/src/install/kubernetes.md index 40344db..cab3f34 100644 --- a/docs/src/install/kubernetes.md +++ b/docs/src/install/kubernetes.md @@ -3,34 +3,13 @@ This section explains how to install lockc on a Kubernetes cluster with [helm](https://helm.sh/). -The helm chart is available on [lockc-helm-chart](https://github.com/rancher-sandbox/lockc-helm-charts) git repository. -Installation with default values can be done with: +The helm chart is available on [lockc-helm-chart](https://rancher-sandbox.github.io/lockc-helm-charts/) +website. Installation with default values can be done with: ```bash -repo add lockc https://rancher-sandbox.github.io/lockc-helm-charts/ -helm install install --create-namespace -n lockc lockc lockc/lockc +kubectl apply -f https://rancher-sandbox.github.io/lockc-helm-charts/namespace.yaml +helm repo add lockc https://rancher-sandbox.github.io/lockc-helm-charts/ +helm install -n lockc lockc lockc/lockc ``` More info on lockc helm chart installation can be found [here](https://rancher-sandbox.github.io/lockc-helm-charts) - -To use your own container image, you can override values. Please refer to the -[Container image](../build/container-image.md) section for instructions about -building container images with lockc. Let's assume that you pushed an image -with lockc to `ttl.sh/caa530ed-1371-43f7-a9ad-293a4f930f83:30m`. In that case, -installation with that image can be done with the following command: - -```bash -helm install lockc lockc/lockc --namespace lockc \ - --set lockcd.image.repository=ttl.sh/caa530ed-1371-43f7-a9ad-293a4f930f83 \ - --set lockcd.image.tag=30m -``` - -Enabling debug logs can be helpful for troubleshooting or development. That can -be done with the following command: - -```bash -helm install lockc lockc/lockc/ --namespace lockc \ - --set lockcd.image.repository=ttl.sh/caa530ed-1371-43f7-a9ad-293a4f930f83 \ - --set lockcd.image.tag=30m \ - --set lockcd.debug.enabled=true -```