[skip ci] Doc updates related to help reorg, option renaming, TLS #2939
Conversation
|
|
||
| If you are deploying the virtual container host to a vCenter Server cluster, the datastore that you designate in the `container-store` option must be shared by at least two ESXi hosts in the cluster. Using non-shared datastores is possible, but limits the use of vSphere features such as DRS and High Availability. | ||
| The size of the key for `vic-machine create` to use when it creates auto-generated trusted certificates. If not specified, `vic-machine create` creates keys with default size of 2048 bits. |
There was a problem hiding this comment.
maybe warn against using smaller key size here as 2048 should be considered a minimum
https://github.com/ssllabs/research/wiki/SSL-and-TLS-Deployment-Best-Practices#11-use-2048-bit-private-keys
There was a problem hiding this comment.
Updated text and example:
If not specified, vic-machine create creates keys with default size of 2048 bits. It is not recommended to use key sizes of less than 2048 bits.
--certificate-key-size 3072
|
lgtm but im not an expert in all of these areas |
| @@ -1,4 +1,6 @@ | |||
| # vSphere Integrated Containers Engine Networking Overview # | |||
| # Networks Used by vSphere Integrated Containers Engine # | |||
There was a problem hiding this comment.
Very minor detail - Networks used ...
There was a problem hiding this comment.
Actually, this is a heading, so the upper-case U is normal :)
|
Changes related to the renaming of |
|
|
||
| Short name: None | ||
|
|
||
| The thumbprint of the vCenter Server or ESXi host certificate. Specify this option if your vSphere environment uses untrusted, self-signed certificates. Alternatively, specifying the `--force` option allows you to omit the `--thumbprint` option. If your vSphere environment uses trusted certificates that are signed by a known Certificate Authority (CA), you do not need to specify the `--thumbprint` option. |
There was a problem hiding this comment.
@dougm do you know how this interacts with custom CA bundles on the client system?
| @@ -43,6 +43,21 @@ Wrap the password in single quotation marks (') on Mac OS and Linux and in doubl | |||
|
|
|||
| <pre>--password '<i>esxi_host_or_vcenter_server_p@ssword</i>'</pre> | |||
|
|
|||
| ### `thumbprint` ### | |||
There was a problem hiding this comment.
@stuclem I recommend having a section with common options.
Target, user, password, and thumbprint are common to all vic-machine commands.
I suspect we'll end up making -force, -timeout (or similar), and -debug common across the set as well eventually.
It's going to be painful to duplicate the help for those across all the sections.
There was a problem hiding this comment.
It'll also be too painful to try to do this for 0.7. Opened #2978 to examine whether we can do this for GA. If we were in DITA, it would be easy to single-source the doc and reuse it in each command, but since we're in Markdown it's all manual and so updates are indeed a maintenance headache.
|
|
||
| To obtain the thumbprint of the vCenter Server or ESXi host certificate, run `vic-machine delete` without the specifying the `--thumbprint` or `--force` options. The deletion of the virtual container host fails, but the resulting error message includes the required certificate thumbprint. | ||
|
|
||
| <pre>Failed to verify certificate for target=<i>vcenter_or_esxi_host</i> (thumbprint=<i>thumbprint</i>) |
There was a problem hiding this comment.
There are also messages that you may see about "Certificate has no IP SANS specified" if trying to connect via IP address.
We do need to tidy this error message up - it's a very common one to hit and the error is distinctly unhelpful.
There was a problem hiding this comment.
Decided to delete the error message and be less specific. I think that we might need a troubleshooting topic about this, that includes all possible error messages. Filed #2996 to track this for GA.
| @@ -11,10 +11,11 @@ You have deployed a virtual container host. | |||
| 1. On the system on which you run `vic-machine`, navigate to the directory that contains the `vic-machine` utility. | |||
| 2. Run the `vic-machine inspect` command. | |||
|
|
|||
| The following example includes the options required to obtain information about a named instance of a virtual container host from a simple vCenter Server environment. | |||
| The following example includes the options required to obtain information about a named instance of a virtual container host from a simple vCenter Server environment. You must specify the username and optionally the password, either in the `target` option or separately in the `user` and `password` options. If your vSphere environment uses untrusted, self-signed certificates, you must also specify the thumbprint of the vCenter Server instance or ESXi host in the `thumbprint` option. If the virtual container host has a name other than the default name, `virtual-container-host`, you must specify the `--name` option. | |||
There was a problem hiding this comment.
With any command operating on a specific, existing VCH you can specify, either:
--compute-resource and --name, or
--id (you see this in the ls output - it's actually the vSphere Managed Object Reference, aka moref)
I suspect that in your test env you have a topology that allows for the default value of compute-resource to be useful.
This applies to inspect, delete, and debug. Will also apply to configure when we have that.
There was a problem hiding this comment.
I mentioned that --id replaces the --compute-resource and --name options in the topic describing the options for delete and inspect, but not in the topics on running those commands. I have now added this detail and mentioned that the IDs are vSphere morefs throughout.
| ## VMware Virtual SAN | ||
| The virtual container host maintains filesystem layers inherent in container images by mapping to discrete VMDK files, all of which can be housed in vSphere datastores on Virtual SAN, NFS, or local disks. | ||
| ## VMware vSAN | ||
| The virtual container host maintains filesystem layers inherent in container images by mapping to discrete VMDK files, all of which can be housed in vSphere datastores on vSAN, NFS, or local disks. |
There was a problem hiding this comment.
which can be housed in shared vSphere datastores, including vSAN and NFS datastores.
We can likely support any type of VMFS based datastore as we're operating using the public APIs. We cannot support vVols as that's a different set of APIs.
There was a problem hiding this comment.
Updated the "housed in..." phrase per your comment. Updated #2730 to add vVols to the list of unsupported features.
|
only made it to developing apps - will pick it up later. |
| @@ -2,6 +2,8 @@ | |||
|
|
|||
| The command line utility for vSphere Integrated Containers Engine, `vic-machine`, provides an `upgrade` command that allows you to upgrade virtual container hosts to a newer version. The options that `vic-machine upgrade` requires depend on the location in your vSphere environment in which you deployed the virtual container host to upgrade. | |||
|
|
|||
| **IMPORTANT**: Due to the substantial changes in vSphere Integrated Containers version 0.7, you cannot use `vic-machine upgrade` to upgrade from version 0.6 to version 0.7. You can use `vic-machine upgrade` to upgrade from more recent builds to version 0.7. | |||
There was a problem hiding this comment.
"to upgrade from more recent builds to version 0.7", we might only guarantee upgrade from GA to newer version. From 0.7 to GA will be best to have.
So not sure if it's okay to declare this. 😄
There was a problem hiding this comment.
Maybe we can keep the statement for now for the open source users, but remove it before we publish the GA docs? I used upgrade this morning from a very recent build to 0.7 and it worked fine. I assume that we definitely don't want to encourage people to upgrade a pre-GA release to GA and then use it in production...
|
minor comments. lgtm to the upgrade part |
|
|
||
| vSphere Integrated Containers Engine allows you to deploy virtual container hosts that implement the following standard Docker authentication options: | ||
|
|
||
| - Two-Way TLS authentication with trusted auto-generated or custom certificates |
There was a problem hiding this comment.
I'd simplify this set:
- mutual authentication with client and server certificates
- server authentication, no client authentication
- no TLS authentication
and discuss the different ways you can acquire/generate/provide certificates as a separate thing to what you're going to use them for.
There was a problem hiding this comment.
Pulling this topic from 0.7 pending rewrite.
|
|
||
| With vSphere Integrated Containers Engine, you can use auto-generated trusted certificates that the virtual container host deployment utility, `vic-machine`, creates for you. You can also use custom trusted certificates that you create yourself. | ||
|
|
||
| If you implement two-way authenticaton with trusted certificates, container developers must have copies of the certificate and key files and must use the `--tlsverify --tlscacert --tlscert --tlskey` options when running Docker commands against the virtual container host. |
There was a problem hiding this comment.
Move the consequence (and reason for) using this config to the top.
Make clear mention that this is the tlsverify configuration seeing as that term is used a lot in docker docs.
There was a problem hiding this comment.
Pulling this topic from 0.7 pending rewrite.
|
|
||
| <pre>--bridge-network <i>distributed_port_group_name</i></pre> | ||
| - Two-way authentication with trusted auto-generated TLS certificates that are signed by a Certificate Authority (CA). Specify the [`tls-cname`](#tls-cname) option when you deploy the virtual container host. | ||
| - Server-side authentication with auto-generated, untrusted TLS certificates that are not signed by a CA, with no client-side verification. Specify the [`no-tlsverify`](#no-tlsverify) option when you deploy the virtual container host. |
There was a problem hiding this comment.
I think we're attempting to provide too much detail in general. We only provide the generation of certificates as a convenience (we do not fully populate the certificate organisation fields for example). This documentation should not be an introduction to TLS, certificates, and how they function.
I think we need to say what we can configure, that it uses standard TLS certificate mechanisms, and the vic-machine options to do so. Anything more is out of scope.
For reference there are different types of certificates - my terminology may be mixed vs what you find on the rest of the net:
- public CA chain (with a public trusted root such as verisign)
- certificates signed by this can be verified by most systems without additional configuration
- self-signed CA
- must install the CA to trust certificates signed by it
- self-signed, no CA
There are then different types of use:
- mutual authentication - client verifies server certificate, server verifies client certificate
- verification is via a trusted root certificate, whether public or installed
- server certificate embeds domain name or IP address in the certificate and this must match the address the client uses
- client verifies server via trusted root
- server certificate embeds domain and IP with which it may be used
- unverified server certificate (self-signed)
- the certificate cannot be verified, but is still used to negotiate TLS
- no TLS
- all communication is unencrypted
There was a problem hiding this comment.
Pulled all of the TLS overview-type content out of the topic for 0.7, pending rewrite.
|
|
||
| <pre>--bridge-network '<i>distributed port group name</i>'</pre> | ||
| **IMPORTANT**: If you assign a static IP address to a virtual container host on the client network by setting the `--client-network-ip` and `--client-network-gateway` options, you do not need to specify any authentication options. Otherwise, it is **mandatory** to specify an authentication option when you deploy a virtual container host. For information about setting a static IP address on a virtual container host, see [Options for Specifying a Static IP Address for the Virtual Container Host Endpoint VM](#static-ip) in Advanced Options. |
There was a problem hiding this comment.
If providing a static client IP and no explicit TLS options, it behaves as if --tls-cname=<ipaddress> has been provide.
Different from not needing to specify options.
|
♻️ |
|
Merging this now to get it into the repo for 0.7. |
Fixes #2591 #2570 #2633 #2791 #2745
There is still work to do on TLS authentication (updating the examples, verify deployment topics) but I wanted to get a review going sooner rather than later.
@hickeng, I imagine that reviewing everything related to TLS falls to/on you, I'm afraid....