Secure vs insecure image pruning #4471

miminar · 2017-05-24T15:26:34Z

Document new options related to secure connection to integrated docker registry and a mechanism that decides whether to fall-back to insecure connection.

Resolves #4232
Resolves bz#1469654

~~Is blocked on openshift/origin#14114?~~ No longer blocked.

miminar · 2017-05-24T15:27:24Z

@legionus PTAL

miminar · 2017-05-31T07:24:10Z

@soltysh PTAL

ahardin-rh · 2017-06-02T16:37:11Z

admin_guide/pruning_resources.adoc

+used by {product-title}, it needs to be specified using
+`--certificate-authority` flag. Otherwise, the prune command will fail with
+error similar to
+link:#using-insecure-connection-against-secured-registry[the one below].


xref:using-insecure-connection-against-secured-registry[the one below]

ahardin-rh · 2017-06-02T16:38:14Z

admin_guide/pruning_resources.adoc

+.^|`--force-insecure`
+|Allow an insecure connection to the docker registry that is hosted
+via HTTP or has an invalid HTTPS certificate. By default, insecure connection
+is allowed only in case where neither certificate-authority nor registry-url is


`certificate-authority` `registry-url`

ahardin-rh · 2017-06-02T16:42:43Z

admin_guide/pruning_resources.adoc

+====
+If the registry is secured by a certificate authority different from the one
+used by {product-title}, it needs to be specified using
+`--certificate-authority` flag. Otherwise, the prune command will fail with


`prune` command

s/with error similar to/with an error similar to

ahardin-rh · 2017-06-02T16:48:56Z

admin_guide/pruning_resources.adoc

+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. By default, the certificate authority data stored in
+user's config are used - the same for communication with the master API.


s/config/configuration file
s/-/--

ahardin-rh · 2017-06-02T16:50:15Z

admin_guide/pruning_resources.adoc

+
+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. By default, the certificate authority data stored in


I would move the code block to just before "By default...." so that the first sentence does not get broken up.

ahardin-rh · 2017-06-02T16:52:34Z

admin_guide/pruning_resources.adoc

@@ -188,14 +188,27 @@ 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


registry, but

ahardin-rh · 2017-06-02T17:37:16Z

admin_guide/pruning_resources.adoc

@@ -283,9 +306,39 @@ $ oadm prune images --keep-tag-revisions=3 --keep-younger-than=60m --confirm
 $ oadm prune images --prune-over-size-limit --confirm
 ----

+.Using secure or insecure connection


Perhaps we can use a discrete heading here instead?

ahardin-rh · 2017-06-02T17:37:42Z

admin_guide/pruning_resources.adoc

 |===

+.Determining images and layers eligible for pruning


Perhaps we can use a discrete heading here instead?

soltysh

I left you some comments.

soltysh · 2017-06-05T10:18:53Z

admin_guide/pruning_resources.adoc

+|Allow an insecure connection to the docker registry that is hosted
+via HTTP or has an invalid HTTPS certificate. By default, insecure connection
+is allowed only in case where neither certificate-authority nor registry-url is
+specified. Whenever possible, use `--certificate-authority` instead of this


I'd move the last sentence as a NOTE below. Additionally, reword this to something like:

Whenever possible use --certificate-authority, instead. Use of this option is strongly discouraged.

I've ditched it. There is plenty of other places advocating the same. Instead, I've put (Dangerous) at the beginning.

soltysh · 2017-06-05T10:21:05Z

admin_guide/pruning_resources.adoc

+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. If provided, a secure
+connection will be initiated. To allow a fall-back to insecure transport, use


Don't encourage using --force-insecure anywhere, so drop the last sentence. It's already explained and that's it, it should not be used anywhere, though.

soltysh · 2017-06-05T10:22:22Z

admin_guide/pruning_resources.adoc

@@ -283,9 +306,39 @@ $ oadm prune images --keep-tag-revisions=3 --keep-younger-than=60m --confirm
 $ oadm prune images --prune-over-size-limit --confirm
 ----

+.Using secure or insecure connection
+
+The secure connection is preferred for production use. It is done over HTTPS


Suggestion:
The secure connection is the preferred and recommended approach.

It's the recommended as a rule, not only for production.

soltysh · 2017-06-05T10:23:35Z

admin_guide/pruning_resources.adoc

+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 following cases unless


s/following/the following

following cases , unless

soltysh · 2017-06-05T10:24:27Z

admin_guide/pruning_resources.adoc

+The fall-back to insecure connection is allowed in following cases unless
+`--certicate-authority` is specified:
+
+1. The prune command is run with `--force-insecure` option.


Add info in parenthesis this is not recommended.

soltysh · 2017-06-05T10:25:39Z

admin_guide/pruning_resources.adoc

+attempts to use secure connection. 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 may force the client to use insecure
+connection by appending `--force-insecure` to the command.


Add not recommended at the end in parens.

miminar · 2017-06-05T10:29:53Z

Now blocked on openshift/origin#14405. I will need to update error messages once it lands.

miminar · 2017-06-27T15:59:21Z

~~Now blocked on openshift/origin#14914~~

miminar · 2017-07-11T11:55:53Z

Thanks for all the comments. They should be addressed now. The dependency PR is still waiting for the unblocked merge queue.

miminar · 2017-10-03T13:29:27Z

No longer blocked. @ahardin-rh could you please review once more?

miminar · 2017-10-03T13:33:07Z

I'd like to make some corrections for earlier releases. Shall I re-open this against enterprise-3.6 and enterprise-3.5?

bparees · 2017-10-03T18:09:18Z

@miminar if we label this PR for 3.5 and 3.6, the changes will be applied there.

if 3.5 and 3.6 need a different set of doc, then you'll need to open a separate PR and only label it for 3.5 and 3.6.

bparees · 2017-10-03T18:10:04Z

@miminar so which versions is this specific PR appropriate for?

miminar · 2017-10-04T08:57:28Z

@bparees 3.6 - latest; I'll re-submit new PRs for 3.4 and 3.5

ahardin-rh · 2017-10-04T17:09:28Z

admin_guide/pruning_resources.adoc

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

+[discrete]
+==== Images not being pruned


Images Not Being Pruned

ahardin-rh · 2017-10-04T17:10:26Z

admin_guide/pruning_resources.adoc

@@ -342,6 +392,58 @@ 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 secure connection against insecure registry


Using a Secure Connection Against an Insecure Registry

ahardin-rh · 2017-10-04T17:13:04Z

admin_guide/pruning_resources.adoc

+[[using-secure-connection-against-insecure-registry]]
+==== Using secure connection against insecure registry
+
+If you see similar message in the output of the `oadm prune images` command:


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

ahardin-rh · 2017-10-04T17:14:25Z

admin_guide/pruning_resources.adoc

+It means that your registry is not secured and the `oadm prune images` client
+attempts to use secure connection. 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 may force the client to use insecure


you can force the client to use an insecure

ahardin-rh · 2017-10-04T17:14:43Z

admin_guide/pruning_resources.adoc

+connection by appending `--force-insecure`  to the command *(not recommended)*.
+
+[[using-insecure-connection-against-secured-registry]]
+==== Using insecure connection against secured registry


Using an Insecure Connection Against a Secured Registry

ahardin-rh · 2017-10-04T17:16:56Z

admin_guide/pruning_resources.adoc

+By default, the certificate authority data stored in user's configuration file
+are used -- the same for communication with the master API.
+
+Use `--certificate-authority` option to provide the right certificate authority


ahardin-rh · 2017-10-04T17:18:30Z

admin_guide/pruning_resources.adoc

+
+[discrete]
+[[using-wrong-certificate-authority]]
+==== Using wrong certificate authority


Using the Wrong Certificate Authority

ahardin-rh · 2017-10-04T17:19:04Z

admin_guide/pruning_resources.adoc

+[[using-wrong-certificate-authority]]
+==== Using wrong certificate authority
+
+The following error means that certificate authority used to sign the


that the certificate

ahardin-rh · 2017-10-04T17:19:13Z

admin_guide/pruning_resources.adoc

+==== Using wrong certificate authority
+
+The following error means that certificate authority used to sign the
+certificate of the secured Docker registry is different from the authority used


different than

Docker registry

ahardin-rh · 2017-10-04T17:19:53Z

admin_guide/pruning_resources.adoc

+
+Make sure to provide the right one with the flag `--certificate-authority`.
+
+As a work-around, the `--force-insecure` flag may be added instead *(not


can be added instead

ahardin-rh · 2017-10-04T17:20:31Z

admin_guide/pruning_resources.adoc

+`--registry-url`.
+
+.^|`--force-insecure`
+|*(Dangerous)* Allow an insecure connection to the docker registry that is


Docker registry

ahardin-rh · 2017-10-04T17:20:51Z

admin_guide/pruning_resources.adoc

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


Docker registry

ahardin-rh · 2017-10-04T17:26:37Z

@miminar Thanks! Just a few minor comments from me.

Just a heads-up that, given our new docs workflow, if you want to submit separate PRs for 3.4 and 3.5, be sure to do so against enterprise-3.4-stage and enterprise-3.5-stage respectively. Thanks again!

miminar · 2017-10-05T09:29:12Z

@ahardin-rh thanks a lot! Comments should be addressed now.

Document new options related to secure connection to integrated docker registry and a mechanism that decides whether to fall-back to insecure connection. Signed-off-by: Michal Minář <[email protected]>

ahardin-rh · 2017-10-05T13:37:05Z

@miminar Excellent. Thank you!

ahardin-rh · 2017-10-05T13:43:45Z

[rev_history]
|xref:../admin_guide/pruning_resources.adoc#admin-guide-pruning-resources[Pruning Objects]
|Added details on secure versus insecure image pruning.
%

miminar mentioned this pull request May 24, 2017

Prefer secure connection during image pruning openshift/origin#14114

Merged

ahardin-rh reviewed Jun 2, 2017

View reviewed changes

soltysh suggested changes Jun 5, 2017

View reviewed changes

miminar changed the title ~~Secure vs insecure image pruning~~ [DO NOT MERGE] Secure vs insecure image pruning Jun 5, 2017

miminar mentioned this pull request Jun 5, 2017

Bug 1450291 - Improve logs in image pruning openshift/origin#14405

Merged

miminar force-pushed the secure-image-pruning branch 2 times, most recently from 1bb8a53 to cecc1f6 Compare July 11, 2017 11:53

miminar mentioned this pull request Aug 8, 2017

pruning images - note the need for --certificate-authority flag when the registry is secured #4232

Closed

miminar force-pushed the secure-image-pruning branch from cecc1f6 to d82651d Compare October 3, 2017 13:28

miminar changed the title ~~[DO NOT MERGE] Secure vs insecure image pruning~~ Secure vs insecure image pruning Oct 3, 2017

miminar force-pushed the secure-image-pruning branch from d82651d to 3b0ca97 Compare October 3, 2017 13:30

bparees self-assigned this Oct 3, 2017

bparees added the branch/dedicated label Oct 4, 2017

ahardin-rh reviewed Oct 4, 2017

View reviewed changes

ahardin-rh removed branch/enterprise-3.6.1 branch/enterprise-3.9 labels Oct 4, 2017

miminar force-pushed the secure-image-pruning branch from da31247 to 63089db Compare October 5, 2017 09:28

Secure vs insecure image pruning

338e0bd

Document new options related to secure connection to integrated docker registry and a mechanism that decides whether to fall-back to insecure connection. Signed-off-by: Michal Minář <[email protected]>

miminar force-pushed the secure-image-pruning branch from 63089db to 338e0bd Compare October 5, 2017 09:31

This was referenced Oct 5, 2017

[3.5] Secure vs insecure image pruning #5535

Merged

[3.4] Secure vs insecure image pruning #5536

Merged

ahardin-rh added this to the Next Release milestone Oct 5, 2017

ahardin-rh merged commit 999c346 into openshift:master Oct 5, 2017

adellape modified the milestones: Next Release, Staging Oct 9, 2017

vikram-redhat modified the milestones: Staging, Published - 10/11/2017 Oct 12, 2017

miminar deleted the secure-image-pruning branch December 3, 2017 08:35


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

		As a work-around, the `--force-insecure` flag may be added instead *(not


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

Secure vs insecure image pruning #4471

Secure vs insecure image pruning #4471

Conversation

miminar commented May 24, 2017 • edited Loading

miminar commented May 24, 2017

miminar commented May 31, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ahardin-rh Jun 2, 2017 • edited Loading

Choose a reason for hiding this comment

ahardin-rh Jun 2, 2017 • edited Loading

Choose a reason for hiding this comment

soltysh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

miminar commented Jun 5, 2017

miminar commented Jun 27, 2017 • edited Loading

miminar commented Jul 11, 2017

miminar commented Oct 3, 2017

miminar commented Oct 3, 2017

bparees commented Oct 3, 2017

bparees commented Oct 3, 2017

miminar commented Oct 4, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ahardin-rh commented Oct 4, 2017

miminar commented Oct 5, 2017

ahardin-rh commented Oct 5, 2017

ahardin-rh commented Oct 5, 2017

miminar commented May 24, 2017 •

edited

Loading

ahardin-rh Jun 2, 2017 •

edited

Loading

ahardin-rh Jun 2, 2017 •

edited

Loading

miminar commented Jun 27, 2017 •

edited

Loading