Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs #358

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from
Open

Update docs #358

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ef1e0d8
Fix links and remove spaces at end of lines
bgandon Jul 6, 2024
70e4828
Consistently name the tech 'RunC' and the CLI `runc`
bgandon Jul 6, 2024
d7a8fbf
Update docs with recent depreciation
bgandon Jul 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 38 additions & 22 deletions docs/opsguide-containerd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,17 @@ why it is important to understand how Guardian is mapping its terminology to the
Here is a table describing that mapping.

```
|---------------|-----------------|----------------------------------------------------------|
| Guardian Term | Containerd Term | RunC Representation |
|---------------|-----------------|----------------------------------------------------------|
| OCI Bundle | Container | The config.json used by runc |
| Container | Task | The running instance of a runc bundle (runc run) |
| Process | Process | A process exec-ed into a running runc bundle (runc exec) |
|---------------|-----------------|----------------------------------------------------------|
|---------------|-----------------|--------------------------------------------------------------|
| Guardian Term | Containerd Term | RunC Representation |
|---------------|-----------------|--------------------------------------------------------------|
| OCI Bundle | Container | The `config.json` used by RunC |
| Container | Task | The running instance of a RunC bundle (`runc run`) |
| Process | Process | A process `exec`-ed into a running RunC bundle (`runc exec`) |
|---------------|-----------------|--------------------------------------------------------------|
```

Another important concept of containerd is the concept of `namespaces`. Each client can work in its own
namespace, so that different clients do not have to give their containers globally unique names. Guardian
Another important concept of containerd is the concept of `namespaces`. Each client can work in its own
namespace, so that different clients do not have to give their containers globally unique names. Guardian
is working in a namespace named "garden".

#### The ctr client
Expand All @@ -32,9 +32,15 @@ Look at [ctr docs](https://github.com/projectatomic/containerd/blob/master/docs/

#### Processes

For the time being the containerd mode is limited to container operations. So even when containerd mode
is on, all process operations are still being handled by "RunDmc" - the runc mode containerizer. Please
have a look at the [runc mode ops guide](opsguide-runc.md#processes) for more details.
The containerd mode is limited to container operations. There has been an
experimental option for handling processes operations by ContainerD instead of
RunC since v1.15.0 (as of 2028-06-18), but it has been deprecated in v1.53.0
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the date is 2024-06-18

(2024-05-16). So even when containerd mode is on, all process operations are
still being handled by the `RunDmc` component - the RunC mode containerizer,
as detailed in [Garden Components][garden_components]. Please have a look at
the [RunC mode ops guide](opsguide-runc.md#processes) for more details.

[garden_components]: https://github.com/cloudfoundry/garden-runc-release/blob/develop/docs/opsguide.md#garden-components

#### The Bundle Config
If you need to look at your RunC bundle config it can be found at:
Expand All @@ -51,7 +57,7 @@ You can also use the `ctr` client:

## Containerizer

RunContainerd is Guardian's containerd mode containerizer. It is a thin wrapper around containerd.
RunContainerd is Guardian's containerd mode containerizer. It is a thin wrapper around containerd.
In order to create and manage containers it relies on a containerd instance running on a unix socket.
The socket path is `/var/vcap/sys/run/containerd/containerd.sock`

Expand All @@ -68,20 +74,30 @@ For example, to execute a process in a container you can execute:

To enable the usage of containerd:

https://github.com/cloudfoundry/garden-runc-release/blob/861e755aed81d437f84f6af709344537578dd6e9/jobs/garden/spec#L212-L214
https://github.com/cloudfoundry/garden-runc-release/blob/861e755/jobs/garden/spec#L212-L214

In addition, in order to enable containerd for container process management:
https://github.com/cloudfoundry/garden-runc-release/blob/861e755aed81d437f84f6af709344537578dd6e9/jobs/garden/spec#L231-L233
This has been GA since garden-runc-release [v1.17.0][gdn-runc_v1.17.0] (after
being introduced as experimental in [v1.15.0][gdn-runc_v1.15.0]), and
integrated by default in cf-deployment [v6.3.0][cf-d_v6.3.0].

For Containerd's daemon:
We set up the config file here: https://github.com/cloudfoundry/garden-runc-release/blob/861e755aed81d437f84f6af709344537578dd6e9/jobs/garden/spec#L22
[gdn-runc_v1.15.0]: https://github.com/cloudfoundry/garden-runc-release/releases/tag/v1.15.0
[gdn-runc_v1.17.0]: https://github.com/cloudfoundry/garden-runc-release/releases/tag/v1.17.0
[cf-d_v6.3.0]: https://github.com/cloudfoundry/cf-deployment/releases/tag/v6.3.0

Containerd's config file is built here: https://github.com/cloudfoundry/garden-runc-release/blob/develop/jobs/garden/templates/config/containerd.toml.erb#L29C17-L51
In addition, in order to enable containerd for container process management (deprecated in v1.53.0):
https://github.com/cloudfoundry/garden-runc-release/blob/861e755/jobs/garden/spec#L231-L233

Garden Start starts up the containerd process by calling the method `start_containerd`: https://github.com/cloudfoundry/garden-runc-release/blob/861e755aed81d437f84f6af709344537578dd6e9/jobs/garden/templates/bin/garden_start.erb#L46
For Containerd's daemon, we set up the config file here:
https://github.com/cloudfoundry/garden-runc-release/blob/861e755/jobs/garden/spec#L22

Which then kicks off the steps to invoke containerd with the previously generated config file: https://github.com/cloudfoundry/garden-runc-release/blob/861e755aed81d437f84f6af709344537578dd6e9/jobs/garden/templates/bin/containerd_utils.erb#L28-L68
Containerd's config file is built here:
https://github.com/cloudfoundry/garden-runc-release/blob/861e755/jobs/garden/templates/config/containerd.toml.erb#L28-L51

Garden's start had previously been accomplished by the configuration of this BPM configuration file: https://github.com/cloudfoundry/garden-runc-release/blob/861e755aed81d437f84f6af709344537578dd6e9/jobs/garden/templates/config/bpm.yml.erb#L1C1-L8C22
Garden Start starts up the containerd process by calling the method `start_containerd`:
https://github.com/cloudfoundry/garden-runc-release/blob/861e755/jobs/garden/templates/bin/garden_start.erb#L46

Which then kicks off the steps to invoke containerd with the previously generated config file:
https://github.com/cloudfoundry/garden-runc-release/blob/861e755/jobs/garden/templates/bin/containerd_utils.erb#L28-L68

Garden's start had previously been accomplished by the configuration of this BPM configuration file:
https://github.com/cloudfoundry/garden-runc-release/blob/861e755/jobs/garden/templates/config/bpm.yml.erb#L1C1-L8C22