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

Secure vs insecure image pruning #4471

Merged
merged 1 commit into from
Oct 5, 2017
Merged

Secure vs insecure image pruning #4471

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
131 changes: 120 additions & 11 deletions admin_guide/pruning_resources.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,13 +191,28 @@ particular namespace makes it impossible to calculate their current usage.

|Option |Description

.^|`--all`
|Include images that were not pushed to the registry, but have been mirrored by
pullthrough. This is on by default. To limit the pruning to images that were
pushed to the integrated registry, pass `--all=false`.

.^|`--certificate-authority`
|The path to a certificate authority file to use when communicating with the
{product-title}-managed registries. Defaults to the certificate authority data
from the current user's config file.
from the current user's configuration file. If provided, secure connection will
be initiated.

.^|`--confirm`
|Indicate that pruning should occur, instead of performing a dry-run.
|Indicate that pruning should occur, instead of performing a dry-run. This
requires a valid route to the integrated Docker registry. If this command is
run outside of the cluster network, the route needs to be provided using
`--registry-url`.

.^|`--force-insecure`
|*Use caution with this option.* Allow an insecure connection to the Docker
registry that is hosted via HTTP or has an invalid HTTPS certificate. See
xref:#pruning-images-secure-or-insecure[Using Secure or Insecure Connections]
for more information.

.^|`--keep-tag-revisions=<N>`
|For each image stream, keep up to at most N image revisions per tag. (default
Expand All @@ -212,14 +227,18 @@ is younger than `<duration>` relative to the current time. (default *60m*)
|Prune each image that exceeds the smallest xref:limits.adoc#image-limits[limit]
defined in the same project. This flag cannot be combined with `--keep-tag-revisions`
nor `--keep-younger-than`.
|===

{product-title} uses the following logic to determine which images and layers to
prune:
.^|`--registry-url`
|The address to use when contacting the registry. The command will attempt to
use a cluster-internal URL determined from managed images and image streams. In
case it fails (the registry cannot be resolved or reached), an alternative
route that works needs to be provided using this flag. The registry host name
may be prefixed by `https://` or `http://` which will enforce particular
connection protocol.
|===

[discrete]
[[image-prune-conditions]]
===== Image Prune Conditions
=== Image Prune Conditions

* Remove any image "managed by {product-title}" (images with the annotation
`*openshift.io/image.managed*`) that was created at least
Expand Down Expand Up @@ -287,9 +306,42 @@ $ oadm prune images --keep-tag-revisions=3 --keep-younger-than=60m --confirm
$ oadm prune images --prune-over-size-limit --confirm
----

[[pruning-images-secure-or-insecure]]
=== Using Secure or Insecure Connections

The secure connection is the preferred and recomended approach. It is done over
HTTPS protocol with a mandatory certificate verification. The `prune` command
always attempts to use it if possible. If not possible, in some cases it can
fall-back to insecure connection, which is dangerous. In this case, either
certificate verification is skipped or plain HTTP protocol is used.

The fall-back to insecure connection is allowed in the following cases unless
`--certificate-authority` is specified:

1. The `prune` command is run with the `--force-insecure` option.
2. The provided `registry-url` is prefixed with the `http://` scheme.
3. The provided `registry-url` is a local-link address or localhost.
4. The configuration of the current user allows for an insecure connection.
This may be caused by the user either logging in using
`--insecure-skip-tls-verify` or choosing the insecure connection when prompted.

[IMPORTANT]
====
If the registry is secured by a certificate authority different from the one
used by {product-title}, it needs to be specified using the
`--certificate-authority` flag. Otherwise, the `prune` command will fail with
an error similar to those listed in
xref:using-wrong-certificate-authority[Using the Wrong Certificate Authority]
or xref:using-insecure-connection-against-secured-registry[Using an Insecure
Connection Against a Secured Registry].
====

[[image-pruning-problems]]
=== Image Pruning Problems

[discrete]
==== Images Not Being Pruned

If your images keep accumulating and the `prune` command removes just a small
portion of what you expect, ensure that you understand
xref:image-prune-conditions[the conditions] that must apply for an image to be
Expand Down Expand Up @@ -342,6 +394,60 @@ them from ever being pruned.
xref:../dev_guide/managing_images.adoc#tag-naming[Learn more about _istag_
naming.]

[discrete]
[[using-secure-connection-against-insecure-registry]]
==== Using a Secure Connection Against Insecure Registry

If you see a message similar to the following in the output of the `oadm prune
images`, then your registry is not secured and the `oadm prune images` client
will attempt to use secure connection:

----
error: error communicating with registry: Get https://172.30.30.30:5000/healthz: http: server gave HTTP response to HTTPS client
----

. The recommened solution is to
xref:../install_config/registry/securing_and_exposing_registry.adoc#securing-the-registry[secure
the registry]. If that is not desired, you can force the client to use an
insecure connection by appending `--force-insecure` to the command *(not
recommended)*.

[[using-insecure-connection-against-secured-registry]]
==== Using an Insecure Connection Against a Secured Registry

If you see one of the following errors in the output of the `oadm prune images`
command, it means that your registry is secured using a certificate signed by a
certificate authority other than the one used by `oadm prune images` client for
connection verification.

----
error: error communicating with registry: Get http://172.30.30.30:5000/healthz: malformed HTTP response "\x15\x03\x01\x00\x02\x02"
error: error communicating with registry: [Get https://172.30.30.30:5000/healthz: x509: certificate signed by unknown authority, Get http://172.30.30.30:5000/healthz: malformed HTTP response "\x15\x03\x01\x00\x02\x02"]
----

By default, the certificate authority data stored in user's configuration file
are used -- the same for communication with the master API.

Use the `--certificate-authority` option to provide the right certificate authority
for the Docker registry server.

[discrete]
[[using-wrong-certificate-authority]]
==== Using the Wrong Certificate Authority

The following error means that the certificate authority used to sign the
certificate of the secured Docker registry is different than the authority used
by the client.

----
error: error communicating with registry: Get https://172.30.30.30:5000/: x509: certificate signed by unknown authority
----

Make sure to provide the right one with the flag `--certificate-authority`.

As a work-around, the `--force-insecure` flag can be added instead *(not
recommended)*.

ifdef::openshift-origin,openshift-enterprise[]
[[hard-pruning-registry]]
== Hard Pruning the Registry
Expand Down Expand Up @@ -432,7 +538,8 @@ resources.
+
----
$ service_account=$(oc get -n default \
-o jsonpath=$'system:serviceaccount:{.metadata.namespace}:{.spec.template.spec.serviceAccountName}\n' dc/docker-registry)
-o jsonpath=$'system:serviceaccount:{.metadata.namespace}:{.spec.template.spec.serviceAccountName}\n' \
dc/docker-registry)
----

.. Add the *system:image-pruner* cluster role to the service account:
Expand All @@ -449,7 +556,8 @@ made:
+
----
$ oc -n default \
exec -i -t "$(oc -n default get pods -l deploymentconfig=docker-registry -o jsonpath=$'{.items[0].metadata.name}\n')" \
exec -i -t "$(oc -n default get pods -l deploymentconfig=docker-registry \
-o jsonpath=$'{.items[0].metadata.name}\n')" \
-- /usr/bin/dockerregistry -prune=check
----
+
Expand All @@ -458,7 +566,8 @@ logging level:
+
----
$ oc -n default \
exec "$(oc -n default get pods -l deploymentconfig=docker-registry -o jsonpath=$'{.items[0].metadata.name}\n')" \
exec "$(oc -n default get pods -l deploymentconfig=docker-registry \
-o jsonpath=$'{.items[0].metadata.name}\n')" \
-- /bin/sh \
-c ‘REGISTRY_LOG_LEVEL=info /usr/bin/dockerregistry -prune=check’
----
Expand Down Expand Up @@ -505,4 +614,4 @@ finished, the registry can be switched back to read-write mode by executing:
----
$ oc env -n default dc/docker-registry REGISTRY_STORAGE_MAINTENANCE_READONLY-
----
endif::[]
endif::[]