Skip to content
This repository has been archived by the owner on Aug 26, 2021. It is now read-only.

Configuration guide

Jump to bottom
Lazarin Lazarov edited this page Apr 11, 2019 · 9 revisions

Overview

This guide describes how to tweak different default settings of Admiral at application level.

Prerequisites

  • You have downloaded the latest official version of Admiral from JFrog Bintray, or
  • You have followed Admiral's Development Guide and built it locally.

And eventually you are able to start Admiral with the run command:

java -jar admiral-host-*.jar --bindAddress=0.0.0.0 --port=8282

Or directly as a container from the Docker Hub image with the Docker command:

docker run -d -p 8282:8282 --name admiral vmware/admiral

Note Due to the significant amount of logs generated it is advisable to include docker log parameters:

--log-driver=json-file --log-opt max-size=100k --log-opt max-file=10

This sample parameters added to docker run command will keep 10 files of 100KB each. Tune according your needs.

See section Configure logging for more info how to change default log level or define own handlers.

Specify a custom "working directory"

By default Admiral puts all the data in some temporary directory randomly generated. If you want to specify your own working directory you can do it by adding the argument sandbox to the run command:

--sandbox=/path/to/admiral/working-directory

Enable SSL

By default Admiral doesn't have SSL enabled, if you want to enable it you have to add the following arguments to the run command:

  • Port where the SSL access is enabled:
--securePort=8383
  • Path to the public key file (in PEM format) to initialize the SSL engine with:
--certificateFile=/path/to/admiral/public.key
  • Path to the private key file (in PEM format) to initialize the SSL engine with:
--keyFile=/path/to/admiral/private.key

Furthermore, if you want to disable the non-SSL access to Admiral, you can do it by setting the standard port to -1 also in the run command:

--port=-1

Then a typical SSL configuration will make use of all the parameters at once, when using the run command:

--securePort=8383 --certificateFile=/path/to/admiral/public.key --keyFile=/path/to/admiral/private.key --port=-1

Or when running it as a container via the ADMIRAL_PORT and XENON_OPTS environment variables:

docker run -d -p 8383:8383 --name admiral -e ADMIRAL_PORT=-1 -e XENON_OPTS="--securePort=8383 --certificateFile=/tmp/public.key --keyFile=/tmp/private.key" -v /path/to/admiral/public.key:/tmp/public.key -v /path/to/admiral/private.key:/tmp/private.key vmware/admiral

Note If you disable the non-SSL access to Admiral and you are using non trusted by default CA generated certificates (e.g. self-signed certificates), you will have to specify a Java key store which includes it:

-Ddcp.net.ssl.trustStore=/path/to/admiral/trusted_certificates.jks
-Ddcp.net.ssl.trustStorePassword=changeit

Or when running it as a container via the JAVA_OPTS environment variable:

-e JAVA_OPTS="-Ddcp.net.ssl.trustStore=/tmp/trusted_certificates.jks -Ddcp.net.ssl.trustStorePassword=changeit" ... -v /path/to/admiral/trusted_certificates.jks:/tmp/trusted_certificates.jks

Enable Authentication

By default Admiral doesn't have any authentication mechanism enabled and anyone is able to access to Admiral's UI and REST API. If you want to enable basic authentication based on a predefined list of legitimate users (something similar to Tomcat's tomcat-users.xml file) you have to do the following:

  • Create a file (e.g. local-users.json) with the following content:
{
  "users": [{
    "email": "admin@admiral.local",
    "password": "Password1!"
  }, {
    "email": "user1@admiral.local",
    "password": "secret1"
  }, {
    "email": "user2@admiral.local",
    "password": "secret2"
  }]
}
  • Add to the run command the argument localUsers pointing to the file you have just created:
--localUsers=/path/to/admiral/local-users.json
  • Or when running it as a container via the XENON_OPTS environment variable:
docker run -d -p 8282:8282 --name admiral -e XENON_OPTS="--localUsers=/tmp/local-users.json" -v /path/to/admiral/local-users.json:/tmp/local-users.json vmware/admiral

Once you have enabled the authentication, when you try to access Admiral's UI, you will be redirected to the default login page, where you have to introduce your username (email) and password. If you want to access via REST API you can request a token with a command like:

$ curl -s -u username:password -v -X POST -d'{"requestType":"LOGIN"}' http://localhost:8282/core/authn/basic -H "Content-Type: application/json"

(Replace http://localhost:8282 with the proper schema, hostname/IP and port if needed.)

And then get the value of the response header x-xenon-auth-token. Next you have to use that value to set the same header in the requests that you want to do to the REST API.

Notes

  • Users emails do not necessarily need to exist, but they have to follow a valid email address format.
  • You will need to clean up your working directory when you switch between non-authenticated and authenticated modes and vice versa.
  • Eventually Admiral will provide role-based access and more secure authentication mechanisms.

Enable the configuration properties file

You can configure a small property file where different settings of Admiral can be tuned. Just create an empty properties file (e.g. conf.properties) and pass its path to the run command as:

-Dconfiguration.properties=/path/to/admiral/conf.properties

Once you have the configuration properties file in place you can tweak the settings below.

Customize the user resources path

Some customizations like containers or images icons and popular templates list (see below) are based on the Admiral user resource folder location which defaults to /etc/xenon/user-resources/. You can change that default location by specifying the new inside the configuration properties file as:

container.user.resources.path=/path/to/admiral/user-resources/

Configure Memory Allocation

The memory requirements for the Admiral management system depend on multiple aspects including the number of nodes in cluster, number of containers and host provisioned or/and under management as well as the level of concurrent usage by different users. Overall this is a very rough guideline of the required memory allocation and depends on the usage the default memory (768M) should be increased to 2GB, 3GB or more.

Containers provisioned and managed Memory per node
by default 512MB or 768M
1,000 ~1.2 GB
2,000 ~2.0 GB
5,000 ~3.3 GB
10,000 ~3.5 GB

The memory allocation could be configured:

*Running in a container

The default options are:

-Xmx768M -Xms768M -Xss256K -Xmn256M -XX:MaxMetaspaceSize=256m

To override the default options:

>docker run -d -p 8282:8282 --name admiral vmware/admiral -e MEMORY_OPTS="-Xmx1024M -Xms1024M -Xss256K -Xmn356M”

*Starting as a Java process

java -Xmx768M -Xms768M -Xss256K -Xmn256M -XX:MaxMetaspaceSize=256m -jar admiral-host-*.jar --bindAddress=0.0.0.0 --port=8282

Enable or disable the option to overwrite the public address for a host

By default, Admiral will think that published ports are accessible on the address that was used to register a given host. Since this is not always the case, it is possible to overwrite this public address from various screens (e.g. Add Cluster, Edit VCH/Docker host). This option is only available if the following entry exists in the configuration properties file:

allow.ft.hosts.public-address=true

The feature is included by default in the standalone and vRA versions of Admiral. In vRA, the public address of the host can also be set during provisioning from the catalog by setting the Container.__publicAddress custom property in the provisioning request form.

Customize the Containers and Images icons

How to change the default icons that identify containers and container images.

How it works?

For every image search, template definition, container instance or application, Admiral will look up for a resource in container-images folder of the defined user resources path based on the image's "namespace/reponame", so for example if you provision a container based on the vmware/photon:1.0 image, it will lookup for a file {user-resources-path}/container-icons/vmware/photon.png and display it if such exists, otherwise it will default to an auto-generated identicon.

How to change the icons?

It's as simple as creating a local folder named container-images and adding icons to it, following the pattern described above, where for the namespace of the image you create a folder and inside that folder a .png file named as the name of the container repository. For example if we want to provide icons for the official alpine and vmware/photon-controller images from https://hub.docker.com/ we would create the following files

  • container-images/library/alpine.png (notice that we use library as namespace, this is the namespace of the official repositories)
  • container-images/vmware/photon-controller.png

Once this is done, based on your setup there are 2 options:

  1. If running the Admiral Java process, copy container-images folder to your Admiral user resources folder (see above).
  2. If running as container, run the Admiral container with:
docker run -d -P -v {full-path-to-container-icons-folder}/:/etc/xenon/user-resources/container-icons/ vmware/admiral

Next time you open Admiral you will see the new icons in all places that are referenced by a container image name.

Note If your browser has already cached the auto-generated identicons icons, make sure to clean up the cache in order to see the new icons.

Customize the Popular Templates list

How to change the Docker images that appear by default in the list of Popular Templates.

How it works?

The list of Popular Templates is loaded by default from an internal configuration file of Admiral.

How to change the list of Images?

You can override that internal configuration file by creating a file called popular-images.json in your Admiral user resources folder (see above) with the following content:

[
  {
    "name": "library/photon",
    "description": "Photon OS is a technology preview of a minimal Linux container host.",
    "registry": "https://registry.hub.docker.com"
  },
  {
    "name": "library/alpine",
    "description": "A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!",
    "registry": "https://registry.hub.docker.com"
  },
  {
    "name": "library/ubuntu",
    "description": "Ubuntu is a Debian-based Linux operating system based on free software.",
    "registry": "https://registry.hub.docker.com"
  }
]

Next time you open Admiral you will see (only) the images specified in that file as the list of Popular Templates.

Configure access to registries behind a proxy

Using the configuration properties file Admiral could access registries through proxy by setting registry.proxy property. Exceptions could be defined by setting registry.no.proxy.list as comma separated list of registries host and port which will be called directly.

registry.proxy=http://myproxy:80
registry.no.proxy.list=registry1.com:12345, registry2.com:5000

Note Container hosts require additional configurations to enable them to work behind proxy. In the case of docker host you can follow this docker doc

Tip Easy way to deploy proxy and monitor its logs is using squid:

docker run --name squid -d --publish 3128:3128 sameersbn/squid:3.3.8-23
docker exec -it squid tail -f /var/log/squid3/access.log

Allow access to plain HTTP registries

In order to increase the security by default in Admiral, from version 1.2.2, the usage of plain HTTP registries is not allowed due to risk of MITM attacks to steal the registry credentials.

Nevertheless, in case you know what you are doing and want to allow the access to plain HTTP registries, you can disable the restriction by adding the following property to the Admiral's configuration properties file (see above).

allow.registry.plain.http.connection=true

Configure logging

Admiral uses Java logging API, default log level is INFO and console handler is used. Configuration is in file /admiral/config/logging.properties.

Log configuration can be modified if custom logging.properties files is mounted to the container. For different formatters, handlers, log level per logger, etc. check Java Logging API.

E.g.: to enable all logs replace INFO with ALL for level property and add mount argument to the run command:

-v /path-custom-config/logging.properties:/admiral/config/logging.properties

Allow usage of TLS v1.0

In order to increase the security by default in Admiral, from version 1.2.2, the usage of TLS v1.0 (in inbound and outbound secure connections) is not allowed due to the BEAST vulnerability. See Wikipedia for more details.

Nevertheless, in case you know what you are doing and want to keep TLS v1.0 (e.g. accessing to some outdated registries which do not support TLS v1.1+), you can disable the TLS v1.0 restriction and allow it by specifying the following system property when Admiral starts.

-Dcom.vmware.admiral.enable.tlsv1=true

Using Admiral

Contributing

Clone this wiki locally