Skip to content

Creating a site on a local system using the Skupper CLI

Using the skupper command-line interface (CLI) allows you to create and manage Skupper sites from the context of the current user.

A typical workflow is to create a site, link sites together, and expose services to the application network.

A local system includes Docker, Podman or Linux system.

If you require more than one site, specify a unique namespace when using skupper, for example skupper --namespace second-site ....

Checking the Skupper CLI and environment

Installing the skupper command-line interface (CLI) provides a simple method to get started with Skupper.

Procedure

  1. Follow the instructions for Installing Skupper.

  2. Verify the installation. 

    skupper version

COMPONENT               VERSION
cli                     2.1.1

  3. For podman sites:

Make sure the Podman socket is available. To enable it: 

systemctl --user enable --now podman.socket
Enable lingering to ensure the site persists over logouts: 
loginctl enable-linger <username>

Creating a simple site using the CLI on local systems

Use the Skupper CLI to create a site on a local system.

Prerequisites

  • The skupper CLI is installed.

By default, all sites are created with the namespace default. On non-Kubernetes sites, you can create multiple sites per-user by specifying a namespace, for example:

skupper site create systemd-site -p linux -n linux-ns
skupper site create docker-site -p docker -n docker-ns

Procedure

  1. Set the SKUPPER_PLATFORM for type of site you want to install:

  2. podman

  3. docker

  4. linux

  5. Install the controller for Podman and Docker sites:

skupper system install
This runs a container to support site, link and service operations. This feature is not available on Linux local system sites (systemd).

Optional: Enable the dynamic system controller to automatically process YAML resources and commands: 

export SKUPPER_SYSTEM_RELOAD_TYPE=auto
skupper system install
Alternatively, you can enable this feature with: 
skupper system install --reload-type auto
With this feature enabled, you can create sites, links, connectors and listeners without needing a system reload to apply your configuration.

Note: When the dynamic system controller is enabled, the skupper system start, skupper system reload, and skupper system stop commands are not needed as configuration changes are automatically applied. Any sites you create are not automatically restarted when the host is restarted. Use this feature for development environments and not for production environments

  1. Create a site:

skupper site create <site-name>
For example: 
skupper site create my-site

Waiting for status...
Site "my-site" is ready.
While the site is created, the site is not running at this point. To run the site: 
skupper system start

Deleting a site using the CLI on local systems

Delete a Skupper site on a local system by using the CLI.

Prerequisites

  • The skupper CLI is installed.

Procedure

  1. Enter the following command to delete a site: 

    skupper site delete <sitename>
skupper system stop

  2. You can also uninstall the controller after deleting all existing sites: 

    skupper system uninstall

Creating a site bundle using the CLI on local systems

Create a site bundle when you want to prepare a site on one system and install it on a remote host.

Sometimes, you might want to create all the configuration for a site and apply it automatically to a remote host. To support this, Skupper allows you create a .tar.gz file with all the required files and an install.sh script to start the remote site.

Prerequisites

  • The skupper CLI is installed. The CLI is not required on the remote site.

Procedure

  1. Set the SKUPPER_PLATFORM for type of site you want to install:

  2. podman

  3. docker

  4. linux

  5. Install the controller for Podman and Docker sites:

skupper system install
This runs a container to support site, link and service operations. This feature is not available on Linux local system sites (systemd).

Optional: Enable the Dynamic System Controller to automatically process YAML resources: 

export SKUPPER_SYSTEM_RELOAD_TYPE=auto
skupper system install
With this feature enabled, you can create sites, links, connectors and listeners without needing a system reload to apply your configuration.

Note: When the dynamic system controller is enabled, the skupper system start, skupper system reload, and skupper system stop commands are not needed as configuration changes are automatically applied.

  1. Create a site:

skupper site create <site-name>
For example: 
skupper site create remote-site

Waiting for status...
Site "remote-site" is ready.
While the site is created, the site is not running and that is not a requirement for this usecase.

  1. Create the bundle: 
     skupper system generate-bundle remote-site
    The output shows the location of the generated .tar.gz file, for example: 
    Site "remote-site" has been created (as a distributable bundle)
Installation bundle available at: /home/user/.local/share/skupper/bundles/remote-site.tar.gz
Default namespace: default
Default platform: podman

  2. Transfer the bundle file to the remote location and uncompress the file in an appropriate location: 

    tar -xzvf remote-site.tar.gz

  3. Start the site: 

    install.sh
    The site is now running, you can verify with skupper site status if the CLI is installed at that location.