vmware/vic-product

vSphere Integrated Containers enables VMware customers to deliver a production-ready container solution to their developers and DevOps teams.

vSphere Integrated Containers

vSphere Integrated Containers (VIC) is comprised of three main components - the vSphere Integrated Containers Engine, Harbor, and Admiral all of which are available as open source on github.

The VIC Engine is a container runtime for vSphere, allowing developers familiar with Docker to develop in containers and deploy them alongside traditional VM-based workloads on vSphere clusters. These workloads can be managed through the vSphere UI in a way familiar to existing vSphere admins.

Harbor, the enterprise container registry, is an enterprise-class registry server that stores and distributes container images. Harbor extends the open source project Docker Distribution by adding the functionalities usually required by an enterprise, such as security, identity and management.

Admiral, the container management portal, provides a UI for developers and app teams to provision and manage containers, including retrieving stats and info about container instances. Cloud administrators will be able to manage container hosts and apply governance to its usage, including capacity quotas and approval workflows. When integrated with vRealize Automation, more advanced capabilities become available, such as deployment blueprints and enterprise-grade Containers-as-a-Service.

With these three capabilities, VIC enables VMware customers to deliver a production ready container solution to their developers and app teams. By leveraging their existing SDDC, customers can now run container-based applications alongside existing virtual machine based workloads in production without having to build out a separate, specialized container infrastructure stack. As an added benefit for customers and partners, VIC is modular. So if your organization already has a container registry in production, you can use that registry with the other components of vSphere Integrated Containers.

Demo

See vSphere Integrated Containers in action in this step by step demo

Installing

Please refer to the documentation and this video for installing and testing VIC.

Support and Troubleshooting

For general questions, visit the vSphere Integrated Containers Engine channel. If you do not have an @vmware.com or @emc.com email address, sign up at https://code.vmware.com to get an invitation.

View the VIC Appliance Troubleshooting Guide

Contributing to vSphere Integrated Containers

Contributors and users are encouraged to collaborate using the following resources:

For cross-component or VIC Appliance issues, please use the vic-product Github issue tracker

For issues relating to individual components, please use the component specific Github issue tracker:

VIC Engine

Harbor

Admiral

Contributing

Please refer to CONTRIBUTING.md for contribution process.

License

The vic-product components are licensed under Apache 2 with additional licenses denoted within each open source repository (VIC, Admiral, Harbor)

vic-product's Issues

Document how to use Admiral to manage the VCH lifecycle

Per comment from @karthik-narayan in #19 (comment).

Document HA support

From @stuclem on May 30, 2016 12:45

Per vmware/vic#744 and vmware/vic#406.

Copied from original issue: vmware/vic#821

Document permitted characters in VCH name

From @stuclem on February 13, 2017 10:45

Per vmware/vic#3552. VCH name validation is implemented in PR vmware/vic#3881.

Copied from original issue: vmware/vic#3910

Update docs to point to downloads on Google Storage rather than Bintray

From @stuclem on March 16, 2017 14:43

Per vmware/vic#4183, we are moving the binary downloads to Google Cloud Storage.

Copied from original issue: vmware/vic#4276

Log bundle HOWTO

From @fdawg4l on December 16, 2016 19:31

Stuart/Nandita,

I'm wondering if we can clarify how to collect a log bundle.

This has how to access vicadmin.
https://vmware.github.io/vic-product/assets/files/html/0.8/vic_admin/access_vicadmin.html

And this has what logs are available.
https://vmware.github.io/vic-product/assets/files/html/0.8/vic_admin/log_bundles.html

The log_bundles page is under Troubleshooting, but it's not clear how to get to vicadmin from there.

Can we add a link back to access_vicadmin from log_bundles? Specifically, I think the following just needs to be a hyperlink.

vSphere Integrated Containers Engine provides log bundles that you can download from the VCH Admin portal for a virtual container host (VCH).

I think if we make VCH Admin portal a link to access_vicadmin, that should help.

The, in access_vicadmin the line which reads,

If the VCH is unable to connect to vSphere, logs that require a vSphere connection are disabled, and you see an error message. You can download the log bundle to troubleshoot the error.

can we make the If...messages. a Note under the Log Bundle with container logs bullet?

Also, "You can download the log bundle to troubleshoot the errror" can be made more general, I think.

---

To aid in troubleshooting errors, you can download the log bundle by

• Going to the VIC Admin portal (link to access_vicadmin)
• And selecting one of the following links
  • Log Bundle
    Contains logs that relate specifically to the VCH that you created
  • Log Bundle with container logs
    Contains the logs for the VCH and also includes the logs regarding the containers that the VCH manages.
    NOTE: If the VCH is unable to...

Copied from original issue: vmware/vic#3529

VIC and a pull through cache

Is it possible to configure VIC to use a pull through cache as per https://docs.docker.com/registry/recipes/mirror/

There is no --registry-mirror option when deploying VIC.

Doc: Break up the vic-machine create options topic and merge in the examples

The vic-machine create options reference is becoming too large to be easily maintainable or navigable. Also, much of the information is duplicated between the options reference and the examples topic.

I propose that we break up the options reference into separate topics that match the sections in vch_installer_options.md, and merge the relevant examples from vch_installer_examples.md into those smaller topics.

Document support for docker compose bundle

From @stuclem on March 16, 2017 14:35

Per vmware/vic#3648, which is merged in vmware/vic#4227

Copied from original issue: vmware/vic#4275

Document how to use Harbor to create users

Per comment from @karthik-narayan in #19 (comment).

Document that any log rotation output is included in the logs

From @stuclem on December 15, 2016 9:32

Per vmware/vic#3300, which is implemented in PR vmware/vic#3302. Might be worth a mention in the log bundles topic, where we mention log rotation.

Copied from original issue: vmware/vic#3515

Document how to use Harbor to create projects

Per comment from @karthik-narayan in #19 (comment).

Document Phone Home feature

From @stuclem on January 31, 2017 10:35

Per vmware/vic#3645. At the least we need to say that the feature exists and list the information that is transmitted.

Copied from original issue: vmware/vic#3776

Document docker cp support

From @stuclem on May 30, 2016 12:36

Document docker cp support, as per vmware/vic#769.

Copied from original issue: vmware/vic#819

VIC for Dev Ops Admins

Document NSX deployment and distributed port group creation

From @stuclem on February 6, 2017 18:48

Per vmware/vic#31.

Copied from original issue: vmware/vic#3854

Document the different debug levels

From @stuclem on May 30, 2016 15:14

Per vmware/vic#709.

Copied from original issue: vmware/vic#852

Document how to use Harbor to set up access to VCHs

Per comment from @karthik-narayan in #19 (comment).

Document vic-machine upgrade --rollback

From @stuclem on March 6, 2017 11:56

Per vmware/vic#3765

Copied from original issue: vmware/vic#4143

Document how to use Harbor to manage images

Per comment from @karthik-narayan in #19 (comment).

Document VCH deployment with running SSHD and custom user and server keys

From @stuclem on February 3, 2017 14:35

Per vmware/vic#3808.

Copied from original issue: vmware/vic#3841

Allow access to PDF of documentation

The vic-product documentation looks great in a web browser, but can't be printed without a lot of trouble. Printing from Chrome, Firefox, or Safari results in a single page that captures what's visible on the screen without the remainder of the document above or below the current screenful. I'd like access to a PDF version that can be printed, read off-line, etc. It appears that GitBooks allows PDF generation, but it must be enabled on a per-book basis:

https://help.gitbook.com/books/how-can-i-provide-a-pdf-version-of-my-book.html

I'd love to see that enabled for all the VIC-related GitBook publications.

Joe Jackson,
Carnegie Mellon University.

Document how to use Admiral to manage containers

Per comment from @karthik-narayan in #19 (comment).

VIC for vSphere Admins

Document support for inventory folders when creating new resources

From @stuclem on February 7, 2017 9:56

Per vmware/vic#3619.

Copied from original issue: vmware/vic#3863

[Question] Support for Windows container hosts planned?

Hey, I'd like to know if you plan to support Windows container hosts in VIC. We have a heterogenous environment and being able to support Windows and Linux docker containers via VIC would be a tremendous value to our business.

Thanks in advance.

• Sebastian

Document that you can identify resources by name rather than path

From @stuclem on February 7, 2017 9:54

Per vmware/vic#3620.

Copied from original issue: vmware/vic#3862

Testing moving issues between repos

From @stuclem on February 7, 2017 16:15

This is a test issue to see what information survives the transfer between repos when using https://github.com/google/github-issue-mover.

Copied from original issue: vmware/vic#3869

Document support for docker rename

From @stuclem on January 31, 2017 14:55

Per vmware/vic#380.

Copied from original issue: vmware/vic#3782

Update the overview

The following files are very Engine-centric and need to be updated:

• https://github.com/vmware/vic-product/blob/master/docs/user_doc/vic_vsphere_admin/introduction.md
• https://github.com/vmware/vic-product/blob/master/docs/user_doc/vic_dev_ops/overview_of_vic_devops.md
• https://github.com/vmware/vic-product/blob/master/docs/user_doc/vic_app_dev/overview_of_vic_appdev.md

Now that we are using Gitbook 3.2.2, we can reuse topics between folders. So, if we can use the same file for both Dev Ops and App Dev, that would be best. TBC.

Developing Container Apps with VIC

Document the unified OVA installer

Per vmware/vic#3917.

Document how to use Harbor to manage projects

Per comment from @karthik-narayan in #19 (comment).

Documentation: improve TLS docs.

From @stuclem on November 8, 2016 12:27

The TLS docs need more work.

Comment from @hickeng by email:

---

I suggest we separate (the TLS doc) in the following manner:

1. How to supply a server certificate for a VCH (this is a really common thing for many servers - should be the piece people are most familiar with).
2. How to configure client authentication (mutual authentication)
3. How to disable TLS
   --> what certificates are required for each of these (certificate authority, server certificate and key, client certificate and key), which role needs which certificates and how they're used in installation.
   --> explicitly not talking about how those certificates are obtained

Then a separate section on the fact that we generate trivial versions of these certificates as a convenience when possible (--tls-cname or --client-network-ip), and that if wanting more control over the certificates than we provide for that the certificates can be generated by standard means (e.g. openssl for linux) or obtained from a certificate provider (https://en.wikipedia.org/wiki/Certificate_authority#Providers)

---

See also:

• The changes to doc/user/usage.md in https://github.com/vmware/vic/pull/3049/files.
• @hickeng 's comments in vmware/vic#2939 (review) , vmware/vic#2939 (review) and vmware/vic#2939 (review)

Copied from original issue: vmware/vic#3055

Document support for NFS volume stores

From @stuclem on February 2, 2017 11:20

Per vmware/vic#3810

Copied from original issue: vmware/vic#3827

Document that vic-machine checks connectivity and name resolution

From @stuclem on November 10, 2016 15:17

Per vmware/vic#3066. Deserves a mention in the following topics

• What happens During Deployment (tracked by vmware/vic#1527)
• The description of the vic-machine create --target option
• A new troubleshooting topic that includes the error message once vmware/vic#3066 is implemented.

Copied from original issue: vmware/vic#3092

Document how to combine vendor supplied server certificate and self-generated Docker client certificates

From @stuclem on February 6, 2017 14:29

Comments from @hickeng in vmware/vic#3745 could serve as a useful example in the docs.

Copied from original issue: vmware/vic#3851

Document ESX firewall configuration mechanism

From @stuclem on February 21, 2017 15:39

Per vmware/vic#3979.

Copied from original issue: vmware/vic#3991

Document how to use Admiral to provision containers

Per comment from @karthik-narayan in #19 (comment).

Documentation: upgrade Gitbook to version 3.2.2

We are currently using version Gitbook 2.6.7. Gitbook 3.2.2 provides much cleaner output for both HTML and PDF, and much better search in HTML, as well as (I believe) support for cross-folder linking. Cross-folder linking is desperately needed for single-sourcing purposes. However, it does not currently work properly on our content. This is mainly because 3.2.2 outputs HTML5, and we use some deprecated HTML tagging in amongst our Markdown. This needs to be cleaned up. Also, the configuration of PDF title pages, headers, and footers is completely different in 3.2.2.

Document changes to contents of VIC Engine bundle

From @stuclem on December 1, 2016 9:15

Per vmware/vic#3388

Copied from original issue: vmware/vic#3420

Clean up https://vmware.github.io/vic-product/

The landing page https://vmware.github.io/vic-product/ is a bit of a mess, and needs to be updated for 1.1 anyway.

Document support for network labels

From @stuclem on March 6, 2017 14:7

Per PR vmware/vic#4138, which addresses vmware/vic#3738.

Copied from original issue: vmware/vic#4145

Doc overhaul for VIC 1.1

This is a proposal for an overhaul of the VIC docs for the next major release:

• We currently have the VIC Engine docs that were authored by @npakrasi and myself for 0.8, and Harbor and Admiral docs that were authored by the Harbor and Admiral engineers. There is little to no crossover between them. There is no overarching doc about how to put the three products together.
  Proposal: Create a unified VIC doc set that covers all three components. The emphasis will be on using all 3 components together, rather than using them independently of each other.
  Potential issue: The use-cases for Harbor and Admiral go beyond the VIC use case. These use-cases will not be documented in the VIC docs.

• The VIC Engine, Harbor, and Admiral docs don’t currently do a very good job of identifying their respective target audiences.
  Proposal: Reorganize into persona-based docs:

  • VIC Overview: description of VIC, description of the different user roles/personas.
  • VIC for vSphere Admins: deploy and manage VCHs, deploy Harbor, deploy Admiral, so that they all work together.
  • VIC for Dev Ops Users: Use Harbor to create and manage projects, create users, set up access to VCHs, manage images. Use Admiral to provision and manage containers and manage the lifecycle of VCHs. Use Admiral to create and deploy containerized apps (or is this the job of the vRA docs?).
  • VIC for Container Developers: supported Docker commands, use and limitations of VIC, using volumes, using private registries, container networking, docker compose examples.
    Potential issue: Would these persona-based docs make it more difficult to find information if you only use one of the components without the other two?

• The docs for Engine, Harbor and Admiral all currently reside in their respective Github repos. Generated PDF/HTML versions of the VIC Engine docs are published to http://vmware.github.io/vic-product via the gh-pages branch of this vic-product repo.
  Proposal: Migrate the Markdown doc files for all 3 components into this repo. Continue to publish PDF/HTML versions for each tagged release to http://vmware.github.io/vic-product.
  Potential Issue: If VIC Engine, Harbor and Admiral do not tag releases at the same time, this might get messy.

• Issue tracking for VIC Engine docs is done in the VIC Engine Github repo. Doc issues do not appear to exist for Harbor or Admiral.
  Proposal: Migrate the VIC Engine doc issues to the vic-product repo. Start creating doc issues for Harbor/Admiral in the vic-product repo.
  Potential Issue: Referencing issues in other repos works. It is also possible to add assignees working in other repos to issues in this repo, e.g. to request doc reviews from Engine/Harbor/Admiral developers. However, if those developers are used to only looking at their assigned issues in the boards for the other repos, any issues in this repo that are assigned to them will not show up in those boards.

• The vic-product repo currently only serves to host the vic-product landing page, http://vmware.github.io/vic-product, and the HTML/PDF versions of the VIC Engine docs.
  Proposal: If the doc source files migrate to the vic-product repo, and if there will be no cross-component code in this repo, rename it to vic-docs. This might help to clarify the confusion between the vic and vic-product repos.
  Potential issue: Will there be any cross-component code, and if so, would it go into the vic-product repo?

Testing cross repo issue-tracking

What happens if we refer to an issue in the /vic repo?

vmware/vic#3782

Document support for docker network create --internal

From @stuclem on March 10, 2017 11:20

Per vmware/vic#3736, which is implemented in PR vmware/vic#4179. This missed the boat for 0.9, so putting it in docs for 1.1.

Copied from original issue: vmware/vic#4213

Document what happens if VC/ESXi certificates are replaced/expire

From @stuclem on November 2, 2016 17:30

Comment from @dougm in vmware/vic#2570 (comment):

---

When using thumbprint based verification, updating the VC/ESX certificate will prevent VIC from managing existing container VMs, creating new ones, etc. However, existing container VMs will continue to run. User will need to use vic-machine to update.

---

According to @emlin, updating certs is not done by vic-machine upgrade.

Copied from original issue: vmware/vic#2984

Documentation: clean up Harbor topics

From @stuclem on March 6, 2017 8:53

The topic https://vmware.github.io/vic-product/assets/files/html/0.8/vic_installation/deploy_vch_harbor.html was thrown together in a hurry at the last minute and definitely needs an overhaul. At the least it needs to be more procedural.

The updated topic should be back-ported into the 0.8 docs.

Copied from original issue: vmware/vic#4142

Document OVA upgrade/patch procedure

From @stuclem on March 2, 2017 14:30

Per vmware/vic#3915

Copied from original issue: vmware/vic#4127

Proper network diagram for complete solution of VIC, Harbor and Admiral

I was trying to deploy this solution in corporate network, but due to a lot of security constrains, it's very hard to make it operations. Taking into account, that local internal infrastructure have almost 200 VLAN's, blocked direct access to Internet, distributed topology and a lot of other security measurements, lacking of proper graphical network diagram - makes it almost impossible to deploy and make operational all 3 components.
It's be great to see, what interfaces, needs what accesses. What components communicates to other internal or external components and on what port and protocol.

Document what happens during VCH deployment

From @stuclem on July 15, 2016 10:56

We should describe all of the configuration checks and validations that occur during VCH deployment in a topic "What Happens During VCH Deployment". Some of these checks are tracked in vmware/vic#1157.

We should also list the operations that occur in vSphere when a VCH is deployed.

Copied from original issue: vmware/vic#1527