Clean up

Remove the images and the Repo resources that nothing uses, or remove an Instance from its cluster.

The examples on this page use the Get started names: the Instance my-instance and the kubectl context kind-jr2. Your output shows your names, sizes and counts.

Know what removes images

You seldom need a command to remove images. jr2 up removes the images that nothing uses at the end of each converge that succeeds. jr2 down removes them after it deletes the namespace. jr2 gc does the same work when you ask for it, for example when your disk is full.

jr2 removes only an image that it built and labeled, and only when no live root in the cluster names it. It removes the image from your computer. On a kind cluster, it also removes it from each node. It does not remove an image from a registry. Converge explains the live roots.

See what jr2 gc removes

Run jr2 gc with --dry-run first. It removes nothing, and it lists each image and each Repo resource that it would remove:

jr2 gc --dry-run

jr2 gc — images on kind-jr2 that no live root names (dry run: nothing is removed)
would sweep 1 image(s) (336.5 MB)
  jr2-sandbox-my-instance-default:6389bdf72d50-amd64
repos: would sweep nothing — every Repo resource is bound by a Machine or was attached within 7d

Here, the image is an old Sandbox Image that the last jr2 up kept on the kind node.

jr2 gc reads the cluster of the current kubectl context. It does not read an Instance folder, so you can run it from any folder. It reads each Instance on the cluster, so it has no -n option. To use a different cluster, add --context <context>.

Remove the images and the Repo resources

jr2 gc

jr2 gc — images on kind-jr2 that no live root names
swept 1 image(s) (336.5 MB)
repos: swept nothing — every Repo resource is bound by a Machine or was attached within 7d

In this output, jr2 gc removed no Repo resource. jr2 gc does not ask you to confirm. It removes a Repo resource when these two conditions are true:

• No registered Machine binds the Repo.
• No run attached the Repo, and nothing made it, in the last 7 days.

After jr2 removes a Repo resource, the Repo cache on each node can remove its copy of the Repo. It removes the copy when nothing on the node uses it. --repo-ttl changes the time limit of the second condition. For example, --repo-ttl 12h removes a Repo resource that no Machine binds and that no run attached in the last 12 hours. --repo-ttl 0 removes each Repo resource that no Machine binds. The last line then gives the count and the time limit: repos: swept 1 Repo resource(s) no Machine binds and no run attached within 0.

Remove an Instance from the cluster

Run jr2 down in the Instance folder:

jr2 down

remove instance "my-instance" from context kind-jr2 (delete namespace "my-instance")? [y/N] y
deleting namespace "my-instance" (runs, store, and Sandboxes go with it)
swept 2 image(s) (317.0 MB)
removed

jr2 down asks you to confirm, unless you add --yes. Type y. Then it deletes the namespace of the Instance and waits until the namespace is gone. These things go with the namespace:

• The Orchestrator and the runs, with the store of the runs.
• Each Sandbox. A commit that is not pushed is lost with its Sandbox.
• The Instance Harness and the conversations that it keeps.
• Each Secret in the namespace. This includes the Instance token and the Secrets that you made with kubectl, for example for harness.envFrom, for a valueFrom in secrets and for the git ssh key.

Then jr2 down removes the images that nothing uses now. The Instance folder does not change.

To put the Instance on the cluster again, make your Secrets again first. Then run jr2 up. When jr2 up makes a new deploy key for git, it is a new key. Register its public key again. See Give the cluster git credentials.

jr2 down does not remove the copies of the Repos on each node. They are in /var/lib/jr2/<namespace>/repos on the node, and nothing uses them. On kind, they are in the node container, and they go when you delete the cluster.

To remove the Instance in CI, add --yes. To remove it from a different namespace or cluster, add -n <namespace> or --context <context>.

Remove the operator too

The operator is in the namespace jr2-system. All the Instances on a cluster share it. When you remove the last Instance, run jr2 down --all in place of jr2 down:

jr2 down --all

remove instance "my-instance" from context kind-jr2 (delete namespace "my-instance" AND the per-cluster operator)? [y/N] y
deleting namespace "my-instance" (runs, store, and Sandboxes go with it)
uninstalling the operator (jr2-system)
swept 2 image(s) (259.1 MB)
removed

Danger

Use --all only when no other Instance is on the cluster. --all deletes the Sandbox and Repo resource types. Thus the Sandboxes and the Repo resources of each Instance on the cluster go with them.

jr2 down --all removes the operator only while the namespace of the Instance is on the cluster. After a plain jr2 down, it refuses with not deployed here …. To remove the operator then, run jr2 up again. Then run jr2 down --all. On kind, you can delete the cluster.

jr2 down --all does not remove the two PriorityClasses that jr2 up adds, jr2-control and jr2-sandbox. To remove them, run this command:

kubectl delete priorityclass jr2-control jr2-sandbox --ignore-not-found

When priorityClasses names your own class for control or sandbox, jr2 up does not add jr2-control or jr2-sandbox for that tier.

Remove the kind cluster

Run jr2 down in each Instance folder. For the last one, add --all. Then delete the kind cluster:

jr2 down --all
kind delete cluster --name jr2

jr2 down removes the images of its Instance from your computer. kind delete cluster cannot do this, because the images are in your docker, not in the cluster. The images that your Dockerfiles name in FROM stay, and so does the build cache of docker.

Rules

• jr2 down runs only in an Instance folder. In a different folder, it exits with the code 1: error: not inside a jr2 instance — no jr2.config.ts found walking up from cwd
• jr2 down with no kubectl context exits with the code 1: error: no kube context — nothing to remove from
• jr2 down refuses a namespace that holds no Instance, and exits with the code 1: not deployed here — namespace "<namespace>" on <context> holds no jr2 instance. Check the context and the namespace. -n and --context change them. jr2 down --all also refuses this way after a plain jr2 down, and the operator stays.
• jr2 down refuses a namespace that belongs to a different Instance, and exits with the code 1: refusing: namespace "<namespace>" on <context> belongs to another instance ("<owner>")
• When you do not type y or yes, jr2 down changes nothing, and exits with the code 1: aborted — nothing was changed
• When no terminal is attached, jr2 down cannot ask, so it changes nothing. It prints <question> — not a tty; pass --yes to proceed non-interactively, then aborted — nothing was changed. It exits with the code 1. Add --yes.
• jr2 down refuses when the Instance and the jr2 CLI do not use the same Kit version. The refusal starts with error: Kit version mismatch — an Instance has one (ADR-0056):. See Fix a failed converge.
• When the namespace is gone but the image sweep fails, jr2 down exits with the code 0. It prints: image sweep failed (<error>) — the instance is still removed. Run jr2 gc later.
• jr2 gc with no kubectl context exits with the code 1: error: no kube context — `jr2 gc` decides what is garbage by asking a cluster what it still needs
• jr2 gc refuses a --repo-ttl that is not a number with d, h or m, or 0. It exits with the code 1 before it reads the cluster: error: --repo-ttl "<ttl>" is not a TTL — use <n>d, <n>h, or <n>m (or 0 for now)
• When jr2 gc cannot read each live root, it removes nothing, and exits with the code 1: error: the roots could not be read (<error>), then nothing was swept — a keep set missing one root would delete images the cluster still needs. The error in the parentheses can come from kubectl, from docker or from a kind node. Fix that cause, then run jr2 gc again.
• When jr2 gc cannot read the Repo resources, it exits with the code 1: error: the Repo resources could not be read (<error>)
• On a kind node, jr2 removes a whole image. Thus it keeps a tag whose image also has a tag that a live root names. It prints: kept <count> tag(s) — their image id also carries a tag a live root names: <tags>. On your computer, jr2 removes each tag that no live root names.
• When docker or a node refuses to remove an image, jr2 prints: failed to remove <count> image(s): <images>
• When jr2 up cannot remove the old images, the converge still succeeds. It prints: images: sweep skipped (<error>) — the converge stands. Run jr2 gc later.

Read next

• Converge
• ADR-0039: why jr2 removes an image when no live root names it.
• ADR-0051: why jr2 gc removes a Repo resource when no Machine binds it and no run attached it in the last 7 days.
• ADR-0019: why jr2 down asks you to confirm.
• jr2 gc, jr2 down
• Cancel a run