Deploying a Local Catalog

Installing and running DC/OS services on a local Catalog datacenter

IMPORTANT: If you are using DC/OS Enterprise, use package-registry for seamless management of packages in air gapped environments. Local Catalog support is deprecated.

You can install and run DC/OS services on a datacenter without Internet access by using a local Catalog. You can deploy a local Catalog that includes all Certified packages (basic), or a local Catalog that includes selected packages (advanced).

Prerequisites:

  • DC/OS CLI installed.

  • Logged into the DC/OS CLI. On DC/OS Enterprise, you must be logged in as a user with the dcos:superuser permission.

NOTE: As the Catalog tarball is over two gigabytes in size it may take some time to download it to your local drive and upload it to each master.

Certified Catalog packages

This section explains how to deploy a local Catalog containing certified Catalog packages.

  1. From a terminal prompt, use the following commands to download the local Catalog and its service definitions onto your local drive.

    curl -v https://s3.amazonaws.com/downloads.mesosphere.io/universe/public/local-universe.tar.gz -o local-universe.tar.gz
curl -v https://raw.githubusercontent.com/mesosphere/universe/version-3.x/docker/local-universe/dcos-local-universe-http.service -o dcos-local-universe-http.service
curl -v https://raw.githubusercontent.com/mesosphere/universe/version-3.x/docker/local-universe/dcos-local-universe-registry.service -o dcos-local-universe-registry.service

  2. Use secure copy (scp) to transfer the Catalog and registry files to a master node, replacing <master-IP> with the public IP address of a master before issuing the following commands. (You can find the public IP address of a master in the top left corner of the DC/OS UI.)

    scp local-universe.tar.gz core@<master-IP>:~
scp dcos-local-universe-http.service core@<master-IP>:~
scp dcos-local-universe-registry.service core@<master-IP>:~

  3. SSH into the master using the following command. Replace <master-IP> with the IP address used in the previous commands.

    ssh -A core@<master-IP>

  4. Confirm that the files were successfully copied.

    ls

    You should see the following files listed.

    dcos-local-universe-http.service  
dcos-local-universe-registry.service  
local-universe.tar.gz

  5. Move the registry files into the /etc/systemd/system/ directory.

    sudo mv dcos-local-universe-registry.service /etc/systemd/system/
sudo mv dcos-local-universe-http.service /etc/systemd/system/

  6. Confirm that the files were successfully copied into /etc/systemd/system/.

    ls -la /etc/systemd/system/dcos-local-universe-*

  7. Load the Catalog into the local Docker instance. This may take some time to complete.

    sudo docker load < local-universe.tar.gz

  8. Restart the systemd daemon.

    sudo systemctl daemon-reload

  9. Enable and start the dcos-local-universe-http and dcos-local-universe-registry services.

    sudo systemctl enable dcos-local-universe-http
sudo systemctl enable dcos-local-universe-registry
sudo systemctl start dcos-local-universe-http
sudo systemctl start dcos-local-universe-registry

  10. Use the following commands to confirm that the services are now up and running.

    sudo systemctl status dcos-local-universe-http
sudo systemctl status dcos-local-universe-registry

Configuring multiple masters

If you only have one master, skip to Linking local Catalog to master below. If you have multiple masters, continue with the following procedure.

  1. Use the following command to discover the private IP addresses of all of your masters. Identify the private IP address of the master you are SSHed into right now from the list. It will match the path shown after core@ip- in your prompt, where the hyphens become periods.

    host master.mesos

  2. Use secure copy to transfer the Catalog and registry files to one of the other masters. Replace <master-IP> with the IP address of the other master.

    scp local-universe.tar.gz core@<master-IP>:~
scp /etc/systemd/system/dcos-local-universe-registry.service core@<master-IP>:~
scp /etc/systemd/system/dcos-local-universe-http.service core@<master-IP>:~

  3. SSH into the master that you just copied these files to.

    ssh -A core@<master_IP>

  4. Confirm that the files were successfully copied.

    ls

    You should see the following files listed.

    dcos-local-universe-http.service  dcos-local-universe-registry.service  local-universe.tar.gz

  5. Move the registry files into the /etc/systemd/system/ directory.

    sudo mv dcos-local-universe-registry.service /etc/systemd/system/
sudo mv dcos-local-universe-http.service /etc/systemd/system/

  6. Confirm that the files were successfully copied into /etc/systemd/system/.

    ls -la /etc/systemd/system/dcos-local-universe-*

  7. Load the Catalog into the local Docker instance. This may take some time to complete.

    sudo docker load < local-universe.tar.gz

  8. Restart the Docker daemon.

    sudo systemctl daemon-reload

  9. Start the dcos-local-universe-http and dcos-local-universe-registry services.

    sudo systemctl start dcos-local-universe-http
sudo systemctl start dcos-local-universe-registry

  10. Confirm that the services are now up and running.

    sudo systemctl status dcos-local-universe-http
sudo systemctl status dcos-local-universe-registry

Repeat this section until you have completed this procedure for all of your masters. Then continue to the Linking local Catalog to master section below.

Linking local Catalog to master

  1. Close the SSH session by typing exit, or open a new terminal prompt. You may have to exit more than one SSH session if you have multiple masters.

  2. (Optional) Use the following command to remove the references to the default Catalog from your cluster. If you want to leave the default Catalog in place and just add the local Catalog as an additional repository, skip to the next step. You can also remove the references to the default Catalog repository from Settings > Package Repositories in the DC/OS web interface.

    dcos package repo remove Catalog

  1. Use the following command to add a reference to the local Catalogs that you added to each master.

    dcos package repo add local-Catalog http://master.mesos:8082/repo

  2. SSH into one of your agent nodes.

    dcos node ssh --master-proxy --mesos-id=<mesos-id>

  3. Use the following commands to download a copy of the DC/OS certificate locally and set it as trusted.

    sudo mkdir -p /etc/docker/certs.d/master.mesos:5000
sudo curl -o /etc/docker/certs.d/master.mesos:5000/ca.crt http://master.mesos:8082/certs/domain.crt
sudo systemctl restart docker

  4. Configure the Apache Mesos fetcher to trust the downloaded Docker certificate.

    1. Copy the certificate:
    sudo cp /etc/docker/certs.d/master.mesos:5000/ca.crt /var/lib/dcos/pki/tls/certs/docker-registry-ca.crt
    1. Generate a hash:
    cd /var/lib/dcos/pki/tls/certs/
openssl x509 -hash -noout -in docker-registry-ca.crt
    1. Create a soft link. You will need to create the /pki/tls/certs directory on the public agent.
    sudo ln -s /var/lib/dcos/pki/tls/certs/docker-registry-ca.crt /var/lib/dcos/pki/tls/certs/<hash_number>.0

  5. Close the SSH session by typing exit, or open a new terminal prompt. Repeat these steps on each agent node.

  6. To verify your success, log into the DC/OS web interface and click the Catalog tab. You should see a list of Certified packages. Install one of the packages.

FAQ

  • I can’t install CLI subcommands

    Packages are hosted at master.mesos:8082. If you cannot resolve or connect to master.mesos:8082 from your DC/OS CLI install, you cannot install CLI subcommands. If you can connect to port 8082 on your masters, add the IP for one of the masters to /etc/hosts.

  • The images are broken

    All Catalog components are hosted inside of your cluster, including the images. The components are served up by master.mesos:8082. If you have connectivity to that IP, you can add it to /etc/hosts and get the images working.

  • I don’t see the package I was looking for

    By default, only Certified packages are bundled. If you’d like to get something else, use the instructions in the next section.

Selected packages

Prerequisite: Git. On Unix/Linux, see these installation instructions.

To deploy a local Catalog containing your own set of packages you must build a customized local Catalog Docker image.

  1. Clone the Catalog repository:

    git clone https://github.com/mesosphere/universe.git --branch version-3.x

  2. Build the universe-base image:

    cd universe/docker/local-universe/
sudo make base

  3. Build the mesosphere/universe Docker image and compress it to the local-universe.tar.gz file. Specify a comma-separated list of package names and versions using the DCOS_PACKAGE_INCLUDE variable. To minimize the container size and download time, you can select only what you need. If you do not use the DCOS_PACKAGE_INCLUDE variable, all Certified Catalog packages are included. To view which packages are Certified, click the Catalog tab in the DC/OS web interface.

    sudo make DCOS_VERSION=1.13 DCOS_PACKAGE_INCLUDE="cassandra:1.0.25-3.0.10,marathon:1.4.2" local-universe

  4. Perform all of the steps as described in Certified Catalog packages.