Skip to main content
Version: 0.6.0

Install kubeslice-cli

Introduction

kubeslice-cli is a command-line tool that allows you to perform KubeSlice operations on Kubernetes clusters. It simplifies the process to install and uninstall the workloads needed to run KubeSlice Controller and Slice Operator in the specified clusters. This tool registers those clusters as part of a KubeSlice multi-cluster, and administer slices across those clusters.

The tool takes input in the form of YAML files that describe the membership of clusters in the multi-cluster (the topology YAML file) as well as the definition of slices across those clusters (the slice configuration YAML file). Given those YAML files, it simplifies installation of KubeSlice by performing all of the necessary configuration steps to apply the appropriate config to each cluster. You can install KubeSlice on your existing kind or cloud clusters.

Alternatively, as a shortcut to create a multicluster of kind clusters to get familiar with KubeSlice, you can use the kubeslice-cli install —profile option. It will create a demo topology with one controller and two worker clusters.

Install the kubeslice-cli Tool

To install the kubeslice-cli tool on different operating systems, download an executable version from the Releases page.

Install kubeslice-cli on Windows

To install kubeslice-cli:

  1. Download the latest Windows version from the Releases page. After downloading the executable file, rename it to kubeslice-cli.exe for ease of use.

  2. Navigate to the directory where you have downloaded the executable file or provide the absolute path to run the kubeslice-cli command.

  3. Ensure the downloaded version is the latest using the following command:

    .\kubeslice-cli.exe --version

Install kubeslice-cli on Linux

To install kubeslice-cli on Linux or Ubuntu:

  1. Download the latest Linux version from the Releases page.

  2. Create a symlink to access the file:

    info

    A symlink is a symbolic Linux/ UNIX link that points to another file or folder on your computer, or a connected file system.

    ln -s <downloaded-binary>  ~/bin/kubeslice-cli
  3. Ensure the downloaded version is the latest using the following command:

    kubeslice-cli --version

Install kubeslice-cli on macOS

To install kubeslice-cli:

  1. Download the latest macOS version from the Releases page.

  2. Fix the error. When you try to install kubeslice-cli on macOS, you get the Unverified Developer Error Message. This error message appears when you try to install an application from a developer who is not registered with Apple.

    mac

    To fix the Unverified developer error message, follow the instructions in enabling the application for macOS.

  3. Create a symlink to access the file:

    info

    A symlink is a symbolic Linux/ UNIX link that points to another file or folder on your computer, or a connected file system.

    ln -s <downloaded-binary>  ~/bin/kubeslice-cli
  4. Ensure the downloaded version is up-to-date using the following command:

    kubeslice-cli --version

Download kubeslice-cli using Wget

See the Releases page for the latest version. Use the following command to download the latest binary (~6 MB):

sudo curl -fL https://github.com/kubeslice/kubeslice-cli/releases/download/<latest-version>/kubeslice-cli-<latest-version>-linux-amd64 -o /usr/local/bin/kubeslice-cli

Example

sudo curl -fL https://github.com/kubeslice/kubeslice-cli/releases/download/0.4.4/kubeslice-cli-0.4.4-linux-amd64  -o /usr/local/bin/kubeslice-cli

Make the binary executable using the following command:

sudo chmod a+x /usr/local/bin/kubeslice-cli

Ensure the downloaded version is the latest using the following command:

kubeslice-cli -v

kubeslice-cli Commands

This section provides an overview of kubeslice-cli commands, their syntax, options, resource types, and some usage examples.

Syntax

Use the following syntax to run the kubeslice-cli tool:

kubeslice-cli [global-options] <command> [<command-arguments>] [command-options]

Commands

The following table describes the syntax and descriptions for all the kubeslice-cli commands.

OperationsSyntaxDescription
createkubeslice-cli create [options]Creates one or more resources from a file.
deletekubeslice-cli delete [options]Delete resources from a file.
describekubeslice-cli describe [options]Describe the KubeSlice resources.
editkubeslice-cli edit [options]Edit and update the definition of one or more kubeSlice resources.
getkubeslice-cli get [options]List one or more kubeSlice resources.
installkubeslice-cli install [options]Install kubeSlice resources.
uninstallkubeslice-cli uninstall [options]Uninstall kubeSlice resources.
helpkubeslice-cli helpGet more information on any command.

Options

The following are the kubeslice-cli options.

OptionsShorthandDescription
--help-hIt provides more information on the kubeslice-cli.
--config-cIt is a global option. The path to the topology configuration YAML file.
--version-vIt is the version of the kubeslice-cli tool.
note

The kubeslice-cli tool must have access to the clusters you want it to manage. To grant it access, set the KUBECONFIG environment variable to a path to the kubeconfig file containing the necessary keys to access those clusters. To set the KUBECONFIG environment variable, use these commands:

  • On Linux/macOS: export KUBECONFIG=<path to kubeconfig file>
  • On Windows: $env:KUBECONFIG = "kubeslice/kubeconfig.yaml"
caution
  • If the global —config option is not specified, kubeslice-cli attempts to execute against the current cluster context. Run the following command to determine which context you are currently in: kubectx -c.
  • The currently supported operations are all controller cluster specific. You must run the kubeslice-cli commands on the controller cluster. use this command to switch the cluster context: kubectx <controller-cluster>.

create

Use this command to create one or more KubeSlice resources. For example, use the create command to create a slice, project, or service export.

Syntax

kubeslice-cli --config <path-to-the-custom-topology-file> create project <project-name> --namespace <controller-namespace>
kubeslice-cli create <sliceConfig|serviceExportConfig> --namespace <project-namespace> --filename <path-to-the-configuration-yaml>

Options

The following are the kubeslice-cli create options.

OptionShorthandDescription
--filename-fIt is the filename, directory, or URL of the file used to create the resource.
--namespace-nIt is the name of the project namespace on the KubeSlice Controller.
--setWorker-wIt is the list of worker clusters to be registered in the SliceConfig.
--config-cIt is a global option. The path to the topology configuration YAML file.
--help-hIt provides information on the create command.

Resource Types

The following are the resource types used with the create command:

  • project: It is used to create, edit, delete, describe, and get the project.
  • sliceConfig: It is used to create, edit, delete, describe, and get the slice.
  • serviceExportConfig: It is used to create, edit, delete, describe, and get the service export.

For more information on resource configuration parameters, see Kubeslice Configuration Parameters.

Examples

The following are the example commands:

  1. To create a slice, use the following command:

    kubeslice-cli create sliceConfig -n <project-namespace> -f <slice-configuration-yaml>

    Example

    kubeslice-cli create sliceConfig -n kubeslice-avesha -f slice-config.yaml

    Example output

    🏃 Running command: /usr/local/bin/kubectl apply -f slice-config.yaml -n kubeslice-demo
    sliceconfig.controller.kubeslice.io/slice-red created

    Successfully Applied Slice Configuration.
  2. To create a project, use the following command:

    Kubeslice-cli create project <project-namespace> -n <controller-namespace>

    Example

    kubeslice-cli create project kubeslice-avesha -n kubeslice-controller

    Example Output

    Creating KubeSlice Project...
    ✔ Generated project manifest project.yaml
    🏃 Running command: /usr/local/bin/kubectl apply -f kubeslice/project.yaml -n kubeslice-controller
    ✔ Applied project.yaml
    Created KubeSlice Project.
  3. To create service export, use the following command:

    kubeslice-cli create serviceExportConfig -f <path-to-the-service-export-yaml> -n <application-namespace>

delete

Use this command to delete the KubeSlice resources. For example, use the delete command to delete a slice, project, or service export. The delete command can also be used to unregister the registered worker cluster. You must offboard the namespaces and delete the slice before unregistering the worker cluster. For more information, see Uninstalling KubeSlice.

Syntax

kubeslice-cli <delete|remove|d> project <project-name> --namespace <controller-namespace>
kubeslice-cli <delete|remove|d> <sliceConfig|serviceExportConfig> <resource-name> --namespace <project-namespace>

Options

The following are the kubeslice-cli delete command options.

NameShorthandUsage
--namespace-nIt is the name of the project namespace on the KubeSlice Controller.
--config-cIt is a global option. The path to the topology configuration YAML file.
--help-hIt provides information on the delete command.

Resource Types

The following are the resource types used with the create command:

  • project: It is used to create, edit, delete, describe, and get the project.
  • sliceConfig: It is used to create, edit, delete, describe, and get the slice.
  • serviceExportConfig: It is used to create, edit, delete, describe, and get the service export.

For more information on resource configuration parameters, see Kubeslice Configuration Parameters

Examples

The following are the example commands:

  1. To delete the slice configuration, use the following command:

    kubeslice-cli delete sliceConfig <sliceConfig-name> -n <project namespace>

    Example

    kubeslice-cli delete sliceConfig blue -n kubeslice-demo

    Example Output

    Deleting KubeSlice SliceConfig...
    🏃 Running command: /usr/local/bin/kubectl delete sliceconfigs.controller.kubeslice.io blue -n kubeslice-demo
    sliceconfig.controller.kubeslice.io "blue" deleted
  2. To delete a project, use the following command:

    kubeslice-cli delete project <project-name> -n <controller-namespace>

    Example

    kubeslice-cli delete project rainbow -n kubeslice-controller

    Example Output

    Deleting KubeSlice Project...
    🏃 Running command: /usr/local/bin/kubectl delete projects.controller.kubeslice.io uma -n kubeslice-controller
    project.controller.kubeslice.io "rainbow" deleted
  3. To delete a registered worker cluster, use the following command:

    kubeslice-cli delete worker <worker-name> -n <project-namespace>

    Example:

    kubeslice-cli delete worker kind-ks-w-4 -n kubeslice-demo

    Example Output

    Deleting KubeSlice Worker...
    🏃 Running command: /usr/local/bin/kubectl delete clusters.controller.kubeslice.io kind-ks-w-4 -n kubeslice-demo
    cluster.controller.kubeslice.io "kind-ks-w-4" deleted

describe

Use this command to describe KubeSlice resources. This shows the details of a specific KubeSlice resource.

Syntax

kubeslice-cli describe project <project-name> --namespace <controller-namespace>
kubeslice-cli describe <sliceConfig|serviceExportConfig> --namespace <project-namespace>

Options

The following are the kubeslice-cli describe command options.

OptionShorthandDescription
--namespace-nIt is the name of the project namespace on the KubeSlice Controller.
--config-cIt is a global option. The path to the topology configuration YAML file.
--help-hIt provides information on the describe command.

Resource Types

The following are the resource types used with the describe command:

  • project: It is used to create, edit, delete, describe, and get the project.
  • sliceConfig: It is used to create, edit, delete, describe, and get the slice.
  • serviceExportConfig: It is used to create, edit, delete, describe, and get the service export.

For more information on resource configuration parameters, see Kubeslice Configuration Parameters.

Examples

The following are the example commands:

  1. To describe the slice configuration, use the following command:

    kubeslice-cli describe sliceConfig <slice-name> -n <project-namespace>

    Example

    kubeslice-cli describe sliceConfig slice-red -n kubeslice-demo

    Example Output

    Describing KubeSlice SliceConfig...
    🏃 Running command: /usr/local/bin/kubectl describe sliceconfigs.controller.kubeslice.io slice-red -n kubeslice-demo
    Name: slice-red
    Namespace: kubeslice-demo
    Labels: <none>
    Annotations: <none>
    API Version: controller.kubeslice.io/v1alpha1
    Kind: SliceConfig
    Metadata:
    Creation Timestamp: 2022-10-04T12:35:54Z
    Finalizers:
    controller.kubeslice.io/slice-configuration-finalizer
    Generation: 1
    Managed Fields:
    API Version: controller.kubeslice.io/v1alpha1
    Fields Type: FieldsV1
    fieldsV1:
    f:metadata:
    f:annotations:
    .:
    f:kubectl.kubernetes.io/last-applied-configuration:
    f:spec:
    .:
    f:clusters:
    f:qosProfileDetails:
    .:
    f:bandwidthCeilingKbps:
    f:bandwidthGuaranteedKbps:
    f:dscpClass:
    f:priority:
    f:queueType:
    f:tcType:
    f:sliceGatewayProvider:
    .:
    f:sliceCaType:
    f:sliceGatewayType:
    f:sliceIpamType:
    f:sliceSubnet:
    f:sliceType:
    Manager: kubectl-client-side-apply
    Operation: Update
    Time: 2022-10-04T12:35:54Z
    API Version: controller.kubeslice.io/v1alpha1
    Fields Type: FieldsV1
    fieldsV1:
    f:metadata:
    f:finalizers:
    .:
    v:"controller.kubeslice.io/slice-configuration-finalizer":
    Manager: manager
    Operation: Update
    Time: 2022-10-04T12:35:54Z
    Resource Version: 60976
    UID: d7fa839e-9b05-4264-adc6-a061850d54d5
    Spec:
    Clusters:
    ks-w-1
    ks-w-2
    Namespace Isolation Profile:
    Isolation Enabled: false
    Qos Profile Details:
    Bandwidth Ceiling Kbps: 30000
    Bandwidth Guaranteed Kbps: 20000
    Dscp Class: AF11
    Priority: 0
    Queue Type: HTB
    Tc Type: BANDWIDTH_CONTROL
    Slice Gateway Provider:
    Slice Ca Type: Local
    Slice Gateway Type: OpenVPN
    Slice Ipam Type: Local
    Slice Subnet: 10.190.0.0/16
    Slice Type: Application
    Events: <none>

edit

Use this command to directly edit any KubeSlice resource you can retrieve through the command line tools. It opens the editor defined by your KUBE_EDITOR, or EDITOR environment variables, or falls back to vi for Linux or notepad for Windows. You can edit multiple objects, although changes are applied one at a time. The command accepts filenames as well as command line arguments, although the files you point to must be previously saved versions of resources. The default format is YAML. In the event of an error while updating, a temporary file is created on disk that contains your unapplied changes. The most common error when updating a resource is another editor changing the resource on the server. When this occurs, apply your changes to the newer version of the resource, or update your temporary saved copy to include the latest resource version.

Syntax

kubeslice-cli <edit|e> project <project-name> --namespace <controller-namespace>
kubeslice-cli <edit|e> <sliceConfig|serviceExportConfig> <resource-name> --namespace <project-namespace>

Options

The following are the kubeslice-cli edit command options.

OptionShorthandDescription
--namespace-nIt is the name of the project namespace on the KubeSlice Controller.
--filename-fIt is the filename, directory, or URL of the file used to create the resource.
--config-cIt is a global option. The path to the topology configuration YAML file.
--help-hIt provides information on the edit command.

Resource Types

The following are the resource types used with create command:

  • project: It is used to create, edit, delete, describe, and get the project.
  • sliceConfig: It is used to create, edit, delete, describe, and get the slice.
  • serviceExportConfig: It is used to create, edit, delete, describe, and get the service export.

For more information on resource configuration parameters, see Kubeslice Configuration Parameters.

Examples

The following are the example commands:

  1. To edit the slice configuration, use the following command:
    kubeslice-cli edit sliceConfig <slice-name> -n <project-namespace>
    Example
    kubeslice-cli edit sliceConfig blue -n kubeslice-demo
  2. To edit the project details, use the following command:
    kubeslice-cli edit project <project name> -n <controller-namespace>
    Examples
    kubeslice-cli edit project demo -n kubeslice-controller
    kubeslice-cli edit project kubeslice-avesha -n kubeslice-controller
  3. To edit the service export, use the following command:
    kubeslice-cli edit serviceExportConfig <resource-name> --namespace <project namespace>
    The <resource-name> is obtained using this command:
    kubeslice-cli get serviceExportConfig -n <project namespace>
    Example
    kubeslice-cli get serviceExportConfig -n kubeslice-demo
    Example Output
    Fetching KubeSlice serviceExportConfig...
    🏃 Running command: /home/eric/bin/kubectl get serviceexportconfigs.controller.kubeslice.io -n kubeslice-demo
    NAME AGE
    iperf-server-iperf-worker-2 4d19h
    Example
    kubeslice-cli edit serviceExportConfig iperf-server-iperf-worker-2 -n kubeslice-demo

get

Use this command to get one or more KubeSlice resources. For example, use the get command to get a slice, project, or service export.

Syntax

kubeslice-cli <get|g> project <project-name> --namespace <controller-namespace>
kubeslice-cli <get|g> <sliceConfig|serviceExportConfig> --namespace <project-namespace>

Options

The following are the kubeslice-cli get command options.

OptionShorthandDescription
--namespace-nIt is the name of the project namespace on the KubeSlice Controller.
--output-oIt supports json and yaml values.
--worker-wIt is the worker cluster name.
--config-cIt is a global option. The path to the topology configuration YAML file.
--help-hIt provides information on the get command.

Resource Types

The following are the resource types used with the get command:

  • project: It is used to create, edit, delete, describe, and get the project.
  • sliceConfig: It is used to create, edit, delete, describe, and get the slice.
  • serviceExportConfig: It is used to create, edit, delete, describe, and get the service export.
  • secrets: It is used to get the secrets of the registered worker clusters from the controller cluster.

For more information on resource configuration parameters, see Kubeslice Configuration Parameters.

Examples

The following are the example commands:

  1. To get the worker details, use the following command:

    kubeslice-cli get worker -n <project-namespace>

    Example

    kubeslice-cli get worker -n kubeslice-demo

    Example Output

    Fetching KubeSlice Worker...
    🏃 Running command: /usr/local/bin/kubectl get clusters.controller.kubeslice.io -n kubeslice-demo
    NAME AGE
    ks-w-1 8m13s
    ks-w-2 8m13s
  2. To get a slice, use the following command:

    kubeslice-cli get sliceConfig -n <project-namespace>

    Example

    kubeslice-cli get sliceConfig -n kubeslice-demo

    Example Output:

    Fetching KubeSlice sliceConfig...
    🏃 Running command: /usr/local/bin/kubectl get sliceconfigs.controller.kubeslice.io -n kubeslice-demo
    NAME AGE
    blue 27s
  3. To get the project details, use the following command:

    kubeslice-cli get project -n <controller-namespace>

    Example

    kubeslice-cli get project -n kubeslice-controller

    Example Output

    Fetching KubeSlice Project...
    🏃 Running command: /usr/local/bin/kubectl get projects.controller.kubeslice.io -n kubeslice-controller
    NAME AGE
    demo 7m6s
  4. To get the list of secrets that belong to project namespace, use the following command:

    kubeslice-cli get secrets <worker-cluster-name> -n kubeslice-demo

    Example 1

    kubeslice-cli get secrets -n kubeslice-demo

    Example Output

    Fetching KubeSlice secret...
    🏃 Running command: /usr/local/bin/kubectl get secrets -n kubeslice-demo
    NAME TYPE DATA AGE
    default-token-6qz9w kubernetes.io/service-account-token 3 73m
    demo-ks-w-1-ks-w-2 Opaque 7 69m
    demo-ks-w-2-ks-w-1 Opaque 1 69m
    kubeslice-rbac-rw-john-token-smmfj kubernetes.io/service-account-token 3 73m
    kubeslice-rbac-worker-ks-w-1-token-rn7dl kubernetes.io/service-account-token 5 73m
    kubeslice-rbac-worker-ks-w-2-token-qld6t kubernetes.io/service-account-token 5 73m

    Example 2

    Use the following command to get the details of secrets in the yaml file.

    kubeslice-cli get secrets -n kubeslice-demo -o yaml
  1. To get the service export, use the following command:
    kubeslice-cli get serviceExportConfig -n <project-namespace>
    Example
    kubeslice-cli get serviceExportConfig -n kubeslice-demo
    Example Output
    Fetching KubeSlice serviceExportConfig...
    🏃 Running command: /usr/local/bin/kubectl get serviceexportconfigs.controller.kubeslice.io -n kubeslice-demo
    NAME AGE
    iperf-server-iperf-worker-2 4d19h

install

Use this command to install the required workloads to run KubeSlice Controller and worker clusters.

Syntax

kubeslice-cli --config <path-to-the-custom-topology-file> <install|i>
kubeslice-cli install <command-options>
kubeslice-cli install --profile=<minimal-demo|full-demo>

Options

The following are the kubeslice-cli install command options.

OptionShorthandDescriptionSupported Values
--profile-pIt is the profile to install or uninstall KubeSlice.full-demo: showcases the KubeSlice inter-cluster connectivity by spawning 3 kind clusters, including 1 KubeSlice Controller and 2 worker clusters, and installing iPerf application to generate network traffic. minimal-demo: sets up 3 kind clusters, including 1 KubeSlice Controller and 2 worker clusters. Generates the Kubernetes manifests for user to manually apply, and verify the functionality.
--skip-sIt skips the installation steps (comma-separated) with minimal-demo and full-demo options.kind: skips the creation of kind clusters. calico: skips the installation of Calico. controller: skips the installation of KubeSlice Controller. worker-registration: skips the registration of worker clusters with the KubeSlice Controller. worker: skips the installation of worker clusters. demo: skips the installation of additional example applications.
--config-cIt is a global option. The path to the topology configuration YAML file.
--help-hIt provides information on the install command.
info

The global option --config and install command option --profile are mutually exclusive and cannot be used together.

Examples

The following are the example commands:

  1. Use the following command to create the kind clusters, install the KubeSlice Controller and worker clusters.

    kubectl-cli install --profile=minimal-demo
  2. To install the KubeSlice using custom topology file, use the following command:

    kubeslice-cli --config <path-to-the-custom-topology-file> install

register

Use this command to register a new worker cluster with the KubeSlice Controller in an existing multi-cluster setup.

Syntax

kubeslice-cli register worker <worker-cluster-name> --namespace <project-namespace>
kubeslice-cli --config <path-to-the-custom-topology-file> <install|i> [options]

Options

The following are the kubeslice-cli register command options.

OptionShorthandDescription
--filename-fIt is the filename, directory, or URL of the file used to create the resource.
--namespace-nIt is the name of the project namespace on the KubeSlice Controller.
--config-cIt is a global option. The path to the topology configuration YAML file.
--help-hIt provides information on the register command.

Resource Type

The worker is the resource type used with the register command.

For more information on resource configuration parameters, see Kubeslice Configuration Parameters.

Examples

The following are the example commands:

info

You must switch the context to the controller cluster to register the worker cluster.

  1. To register a new worker cluster with the KubeSlice Controller in demo setup, use the following command:

    kubeslice-cli register worker <worker-cluster-name> -n kubeslice-demo

    Example

    kubeslice-cli register worker kind-ks-w-4 -n kubeslice-demo

    Example Output

    Registering Worker Clusters with Project...
    ✔ Generated cluster registration manifest kubeslice/custom-cluster-registration.yaml
    🏃 Running command: /usr/local/bin/kubectl apply -f kubeslice/custom-cluster-registration.yaml -n kubeslice-demo
    ✔ Applied kubeslice/custom-cluster-registration.yaml
    Registered Worker Clusters with Project.
  2. To register a new worker cluster with the KubeSlice Controller in an existing multi-cluster setup, use the following command:

    info

    Add a new worker information in the same custom topology file that you used to install KubeSlice. The -s controller option skips the installation of KubeSlice Controller.

    kubeslice-cli --config=<path-to-the-custom-topology-file> install -s controller

uninstall

Use this command to uninstall all the KubeSlice components on kind and cloud clusters.

Syntax

kubeslice-cli <uninstall|cleanup>

Options

The following are the kubeslice-cli uninstall options

OptionShorthandDescription
--config-cIt is a global option. The path to the topology configuration YAML file.
--help-hIt provides information on the delete command.
--all-aUninstalls all the KubeSlice components (worker, controller, and Kubeslice Manager).
--ui-uUninstalls the enterprise user interface component (Kubeslice Manager).

Examples

The following is an example command:

  1. To uninstall the KubeSlice components on kind clusters and delete the kind clusters created using full-demo|minimal-demo option, use the following command:

    kubeslice-cli uninstall
  2. To uninstall the KubeSlice components that were installed using a custom topology file on cloud clusters, use the following command:

    info

    KubeSlice must be uninstalled using the topology file that was used to install it on cloud clusters.

    kubeslice-cli uninstall --config=<path-to-the-custom-topology-file> --all