Skip to content

Commit

Permalink
Documenting dch-photon (vmware#773)
Browse files Browse the repository at this point in the history 
* First mention of dch-photon

* More dch-photon edits

* Adding new file for VCH deployment with dchphoton

* Documenting dch-photon

* Committing so I can swap branches

* More dch-photon updates

* More dch-photon updates

* Typo
  • Loading branch information
@stuclem
stuclem authored Sep 11, 2017
1 parent 8123dfe commit 389e534
Show file tree
Hide file tree
Showing 4 changed files with 148 additions and 19 deletions.
3 changes: 2 additions & 1 deletion docs/user_doc/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,8 @@
* [VCH Deployment Options](vic_vsphere_admin/vch_installer_options.md)
* [Set Environment Variables](vic_vsphere_admin/vic_env_variables.md)
* [Advanced Examples of Deploying a VCH](vic_vsphere_admin/vch_installer_examples.md)
* [Deploy a VCH for Use with vSphere Integrated Containers Registry](vic_vsphere_admin/deploy_vch_registry.md)
* [VCH for Use with Registry](vic_vsphere_admin/deploy_vch_registry.md)
* [VCH for Use with `dch-photon`](vic_vsphere_admin/deploy_vch_dchphoton.md)
* [Use Different User Accounts for VCH Deployment and Operation](vic_vsphere_admin/set_up_ops_user.md)
* [VCH Administration](vic_vsphere_admin/vch_admin.md)
* [Interoperability](vic_vsphere_admin/interop.md)
Expand Down
121 changes: 104 additions & 17 deletions docs/user_doc/vic_app_dev/build_push_images.md
View file
Original file line number Diff line number Diff line change
@@ -1,30 +1,117 @@
# Building and Pushing Images with vSphere Integrated Containers
# Using `dch-photon` to Build and Push Images

The current version of vSphere Integrated Containers Engine does not support `docker build` or `docker push`. As a consequence, the workflow for developing container images and pushing them to a registry server is slightly different to the workflow in a regular Docker environment.

- You use standard Docker to build, tag, and push a container image to a registry.
- You use standard Docker to build, tag, and push a container image to a registry.
- You pull the image from the registry to a vSphere Integrated Containers virtual container host (VCH) to use it.

This topic provides an example of pushing and pulling an image to and from vSphere Integrated Containers Registry. You can use a different private registry server. For simplicity, the example uses the `busybox` container image instead of building a new image.
This release of vSphere Integrated Containers includes an image repository named `dch-photon`, that is pre-loaded in the `default-project` in vSphere Integrated Containers Registry. The `dch-photon` image allows you to deploy a standard Docker container host that runs in a Photon OS container. You can then use this Docker container host to perform `docker build` and `docker push` operations without having to install a local Docker host on your working machine.

**Prerequisites**
- You have access to an image repository. For example, a project repository must exist in vSphere Integrated Containers Registry and you must have a user account that can access that project repository.
- Configure your Docker client to use the vSphere Integrated Containers Registry certificate. For information about how to pass the registry certificate to the Docker client, see [Using vSphere Integrated Containers Registry](configure_docker_client.md#registry) in Configure the Docker Client for Use with vSphere Integrated Containers.
- You have access to a VCH that the vSphere administrator configured so that it can connect to the registry. For information about how deploy a VCH so that it can access a private registry, see the [Private Registry Options](../vic_vsphere_admin/vch_installer_options.md#registry) section of VCH Deployment Options and [Deploy a VCH for Use with vSphere Integrated Containers Registry](../vic_vsphere_admin/deploy_vch_registry.md) in *Install, Deploy, and Maintain the vSphere Integrated Containers Infrastructure*
- In the example, connections to the registry are secured by TLS, but for simplicity the connection between the Docker client and the VCH is not. As a consequence, the Docker commands to run in the VCH do not include any TLS options. If your VCH uses TLS authentication, adapt the Docker commands accordingly, and use port 2376 instead of 2375 when connecting to the VCH. For information about how to connect a Docker client to a VCH that uses TLS authentication, see [Connecting to the VCH](configure_docker_client.md#connectvch) in Configure the Docker Client for Use with vSphere Integrated Containers.

- Configure your Docker client to use the vSphere Integrated Containers Registry certificate. For information about how to obtain the registry certificate and pass it to the Docker client, see [Using vSphere Integrated Containers Registry](configure_docker_client.md#registry) in Configure the Docker Client for Use with vSphere Integrated Containers.
- You have access to a VCH that the vSphere administrator configured so that it can connect to the registry to pull the `dch-photon` image, and so that it has a default volume store. For information about how deploy a VCH for use with `dch-photon`, see the [Deploy a Virtual Container Host for Use with `dch-photon`](../vic_vsphere_admin/deploy_vch_dchphoton.md) in *Install, Deploy, and Maintain the vSphere Integrated Containers Infrastructure*.
- This topic provides an example of using `dch-photon` to push an image to vSphere Integrated Containers Registry and then pull it into a VCH. For simplicity, the example uses a VCH that was deployed with the `--no-tlsverify` option. If your VCH implements TLS verification of clients, you must import the VCH certificates into your Docker client and adapt the Docker commands accordingly. For information about how to connect a Docker client to a VCH that uses full TLS authentication, see [Connecting to the VCH](configure_docker_client.md#connectvch) in Configure the Docker Client for Use with vSphere Integrated Containers.

**Procedure**

1. Pull the `busybox` container image from Docker Hub.<pre>docker pull busybox</pre>In a real-world scenario you would build a new container image rather than pulling the `busybox` image.
2. Tag the image for uploading to the appropriate project repository in vSphere Integrated Containers Registry.<pre>docker tag busybox:1.26 <i>registry_address</i>/<i>project_name</i>/busybox:1.26 </pre>If vSphere Integrated Containers Registry listens for connections on a non-default port, include the port number in the registry address.
3. Log in to vSphere Integrated Containers Registry.<pre>docker login <i>registry_address</i></pre>
3. Push the image from the standard Docker host to vSphere Integrated Containers Registry.<pre>docker push <i>registry_address</i>/<i>project_name</i>/busybox:1.26 </pre>
5. Pull the image from vSphere Integrated Containers Registry into the VCH.<pre>docker -H <i>vch_address</i>:2375 pull <i>registry_address</i>/<i>project_name</i>/busybox:1.26 </pre>
6. List the images that are running in your VCH.<pre>docker -H <i>vch_address</i>:2375 images</pre>
1. Log in to vSphere Integrated Containers Registry from the VCH.

<pre>docker -H <i>vch_address</i>:2376 --tls login <i>registry_address</i></pre>
2. Pull the `dch-photon` image from vSphere Integrated Containers Registry into your VCH.

<pre>docker -H <i>vch_address</i>:2376 --tls pull <i>registry_address</i>/default-project/dch-photon:1.13</pre>

3. Run a `dch-photon` container from the image.

<pre>docker -H <i>vch_address</i>:2376 --tls run --name dch-photon -d -p 12376:2376 <i>registry_address</i>/default-project/dch-photon:1.13 -tlsverify</pre>

This command uses the following Docker options to run the `dch-photon` container:

- `-d`, to run the `dch-photon` container in the background.
- `-p` to map port 12376 on the VCH to the Docker TLS port 2376 on the `dch-photon` container

This command also configures the Docker host that runs in the `dch-photon` container with the following option:

<!-- `-tls`: Enables secure communication with no verification of the remote registry. Loads certificates from `/certs` as `/certs/docker.crt` as the server certificate and `/certs/docker.key` as the key for the server certificate.-->
- `-tlsverify`: Verifies the client and server certificates for the connection from the Docker host running in the `dch-photon` container to the registry.
<!-- - `-vic-ip`: Sets the IP address of the VCH for automatic certificate creation when `dch-photon` is running behind a port mapping.-->

4. Run `docker ps` on the VCH to see the status of the running `dch-photon` container.

<pre>docker -H <i>vch_address</i>:2376 --tls ps</pre>

In the output you see details of the port mapping from port 12376 on the VCH to port 2376/tcp on the `dch-photon` container.

4. Run `docker info` on the mapped port 12376 to obtain information about the Docker host running in the `dch-photon` container.

Note that this command specifies port 12376, because you are running the command in the Docker host in the `dch-photon` container.

<pre>docker -H <i>vch_address</i>:12376 --tls info</pre>

In the output you see that this is a regular Docker 1.13.1 host.

6. Create the folder structure for the registry certificate in the `dch-photon` container.

The `dch-photon` container requires the CA certificate of the registry server. Note that these commands specify port 2376, because you are running them in the VCH.

- First create a folder named `/etc/docker/certs.d`.<pre>docker -H <i>vch_address</i>:2376 --tls exec dch-photon mkdir /etc/docker/certs.d</pre>
- Then create a subfolder with the same name as the registry address, to contain the certificate.<pre>docker -H <i>vch_address</i>:2376 --tls exec dch-photon mkdir /etc/docker/certs.d/<i>registry_address</i></pre>

7. Copy the CA certificate of the vSphere Integrated Containers Registry into the certificates folder in the `dch-photon` container.

Note that this command specifies port 2376.

<pre>docker -H <i>vch_address</i>:2376 --tls cp <i>local_cert_path</i>/ca.crt dch-photon:/etc/docker/certs.d/<i>registry_address</i>/ca.crt</pre>

7. Restart the `dch-photon` container.

Restarting the container allows the Docker host that is running inside it to load the certificate.

Note that this command specifies port 2376.

<pre>docker -H <i>vch_address</i>:2376 --tls restart dch-photon</pre>

5. Create a simple `Dockerfile` and save it in the current directory.

<pre>FROM debian:latest

RUN apt-get update -y && apt-get install -y fortune-mod fortunes

ENTRYPOINT ["/usr/games/fortune", "-s"]</pre>

6. Build an image from the `Dockerfile` in the `dch-photon` Docker host, and tag it with the path to a project in vSphere Integrated Containers Registry.

Note that this command specifies port 12376.

<pre>docker -H <i>vch_address</i>:12376 --tls build -t <i>registry_address</i>/default-project/test-container .</pre>

8. Log in to vSphere Integrated Containers Registry from the `dch-photon` Docker host.

Note that this command specifies port 12376.

<pre>docker -H <i>vch_address</i>:12376 --tls login <i>registry_address</i></pre>

6. Push the image from the `dch-photon` Docker host to the registry.

Note that this command specifies port 12376.

<pre>docker -H <i>vch_address</i>:12376 --tls push <i>registry_address</i>/default-project/test-container</pre>

6. Pull the image from the registry into the VCH.

Note that this command specifies port 2376.

<pre> docker -H <i>vch_address</i>:2376 --tls pull <i>registry_address</i>/default-project/test-container</pre>

6. Run a container from this image on the VCH.

<pre> docker -H <i>vch_address</i>:2376 --tls run <i>registry_address</i>/default-project/test-container</pre>

6. List the containers that are running in the VCH.

<pre>docker -H <i>vch_address</i>:2376 --tls ps</pre>

**Result**

The image that you pulled from vSphere Integrated Containers Registry appears in the list of images that are available in this VCH.
<pre>
REPOSITORY TAG IMAGE ID
<i>registry_address</i>/<i>project_name</i>/busybox 1.26 7e156d496c9f</pre>
The container that you ran from an image that you built and pushed to vSphere Integrated Containers Registry in `dch-photon` appears in the list of containers that are running in this VCH.
2 changes: 1 addition & 1 deletion docs/user_doc/vic_app_dev/configure_docker_client.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ This example configures a Linux Docker client so that you can log into vSphere I
2. Switch to `sudo` user.<pre>$ sudo su</pre>
2. Create a subfolder in the Docker certificates folder, using the registry's IP address as the folder name.<pre>$ mkdir -p /etc/docker/certs.d/<i>registry_ip</i></pre>
3. Copy the registry's CA certificate into the folder.<pre>$ cp ca.crt /etc/docker/certs.d/<i>registry_ip</i>/</pre>
6. Open a new terminal and attempt to log in to the registry server, specifying the IP address of the registry server.<pre>$ docker login <i>registry_ip</pre>
6. Open a new terminal and attempt to log in to the registry server, specifying the IP address of the registry server.<pre>$ docker login <i>registry_ip</i></pre>
7. If the login fails with a certificate error, restart the Docker daemon.<pre>$ sudo systemctl daemon-reload</pre> <pre>$ sudo systemctl restart docker</pre>

### Docker on Windows ###
Expand Down
41 changes: 41 additions & 0 deletions docs/user_doc/vic_vsphere_admin/deploy_vch_dchphoton.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Deploy a Virtual Container Host for Use with `dch-photon` #

This version of vSphere Integrated Containers includes an image repository named `dch-photon`, that is pre-loaded in the `default-project` in vSphere Integrated Containers Registry.

The `dch-photon` image allows container developers to deploy a standard Docker container host that runs in a Photon OS container. Container developers can use this Docker engine to perform operations in standard Docker. For example, developers can use `dch-photon` containers to perform operations that virtual container hosts (VCHs) do not support in this version of vSphere Integrated Containers, such as `docker build` and `docker push`.

For container developers to be able to deploy containers from the `dch-photon` image, you must deploy VCHs with a specific configuration.

**Prerequisites**

- You downloaded the vSphere Integrated Containers Engine bundle from http://<i>vic_appliance_address</i>.
- Obtain the vCenter Server or ESXi host certificate thumbprint. For information about how to obtain the certificate thumbprint, see [Obtain the Certificate Thumbprint of vCenter Server or an ESXi Host](obtain_thumbprint.md).

**Procedure**

1. Log in to the vSphere Integrated Containers Management Portal with a vSphere administrator, Cloud Admin or DevOps admin user account.

vSphere administrator accounts for the Platform Services Controller with which vSphere Integrated Containers is registered are automatically granted Cloud Admin access.
2. Go to **Administration** > **Configuration**, and click the link to download the **Registry Root Cert**.
3. Use `vic-machine create` to deploy a VCH.

- The VCH must be able to pull the `dch-photon` image from the vSphere Integrated Containers Registry instance. You must specify the registry's CA certificate by using the [`--registry-ca`](vch_installer_options.md#registry-ca) option.
- A `dch-photon` container creates an anonymous volume, and as such requires named `default`.

For simplicity, this example deploys a VCH with the `--no-tls` flag, so that container application developers do not need to use a TLS certificate to connect a Docker client to the VCH. However, the connection between the VCH and the registry still requires certificate authentication.<pre>vic-machine-<i>operating_system</i> create
--target '[email protected]':<i>password</i>@<i>vcenter_server_address</i>/dc1
--compute-resource cluster1
--image-store datastore1
--bridge-network vch-bridge
--name vch_dch_photon
--thumbprint <i>vcenter_server_certificate_thumbprint</i>
--no-tlsverify
--registry-ca <i>cert_path</i>/ca.crt
--volume-store <i>datastore_name</i>:default
</pre>

You could also specify <code>--volume-store nfs://datastore_name/path_to_share_point:default</code> to designate an NFS share point as the default volume store.

**Result**

The VCH that you deployed can access vSphere Integrated Containers Registry, and has a volume store named `default`. It is ready for container developers to use with `dch-photon` containers.

0 comments on commit 389e534

Please sign in to comment.