IRCTL for Kubernetes supported self-hosted integration runtime (Preview)

  • Article

In order manage your Microsoft Purview Kubernetes SHIR locally, you need a command line tool named IRCTL. You can download this tool during the SHIR creation process. IRCTL is a command line tool to manage your Microsoft Purview SHIR.

Prerequisites

The system requirements for IRCTL are:

  • Machine running IRCTL - OS is Linux or Windows supporting TLS 1.2
  • The machine to run IRCTL should be able to connect to the following endpoints:
Domain name Outbound ports Description
China: *.compute.governance.azure.cn 443 Required to connect to Microsoft Purview service. If you use Microsoft Purview Private Endpoints, this endpoint is covered by account private endpoint.
  • Kubernetes context: Kubernetes context, which contains Kubernetes cluster information and user’s permissions and credential for this cluster, is needed to talk to your Kubernetes cluster. To ease the configuration for the user’s permissions for SHIR management, you can start with Kubernetes Admin role. This context is generated with the setup of your Kubernetes cluster and saved in a config file. Where and how you can get this file depends on your setting up the Kubernetes cluster.
    • If you use kubeadm init to set up the Kubernetes cluster, you can find the config file under /etc/Kubernetes/admin.conf.
    • If you use AKS, you can follow the guidance of AKS to use Az PowerShell module command to get credentials of this cluster to your local machine. The context can be merged to the config file under $HOME/.kube/config directly.
    • If you're using other tools setting up a Kubernetes cluster, refer to the Kubernetes documentation.
    • As you have the config file of the Kubernetes context, merge it to the config file, which is $HOME/.kube/config, on the machine you would like to run IRCTL command. Or you can set the config file of the Kubernetes context in an environment variable named KUBECONFIG as well. For more information about the Kubernetes context, see Configure Access to Multiple Clusters.

Install and run IRCTL

To control and manage a Kubernetes supported self-hosted integration runtime, users can download a command line tool named IRCTL. Users can also monitor the status on the Portal by IRCTL and kubectl command line. The following are the steps to your Kubernetes supported self-hosted integration runtime.

Download Latest IRCTL for Windows

Specific version

To download a specific version of the IRCTL, change the version segment in the URL: https://aka.ms/purview-irctl/irctl-windows-<version>.tar.gz

For example for version 1.0.0: https://aka.ms/purview-irctl/irctl-windows-1.0.0.tar.gz

Available IRCTL versions can be found in the IRCTL release notes.

After you have downloaded the tool:

  1. Unzip and open the tool folder.

  2. Move it to a location on your machine where you can access it from the command line.

  3. Open the command line and navigate to the folder where the IRCTL application is housed.

  4. Use the below commands to interact with IRCTL and follow these steps to install a Kubernetes supported integration runtime.

IRCTL command details

You can download the IRCTL command line tool from your integration runtime settings in Microsoft Purview. Select your integration runtime and under Settings you can see the Download IRCTL and install integration runtime link. Select it to download the tool.

You can use the IRCTL command line to set up or manage a Kubernetes supported self-hosted integration runtime. Use this syntax to run IRCTL commands from your terminal window:

./irctl [command][flags]...
  • Command specifies the operation you want to perform
  • Flags specifies parameters for the operation
Command Description
config Manages IRCTL configurations
create Create a new SHIR resource
delete Delete an SHIR resource
describe Describes the SHIR running on the Kubernetes cluster
help Provides help about any command
storage Manage local storage reserved for SHIR
log Manage logs of SHIR
upgrade Upgrade an SHIR to the same version with IRCTL

Config

Manage IRCTL configurations.

./irctl config [flags]
./irctl config [command]
Command Description
set Modify one SHIR configuration.
view View all SHIR configurations.
Flag Parameter type Description
-h,--help Help for config

Config set

Modify one self-hosted integration runtime configuration.

./irctl config set <config-name> <config-value> [flags]
Flag Parameter type Description
-c, --context string Name of the Kubernetes context to use, if not specified, current context of Kube config will be used.
-h,--help Help for config

Config view

View all SHIR configurations.

./irctl
Flag Parameter type Description
-c, --context string Name of the Kubernetes context to use, if not specified, current context of Kube config will be used.
-h,--help Help for config

Allowed SHIR Configurations

Config name Config type Valid values Default value (value unset) Description Persists through reinstallation
autoUpdate.enabled Boolean true/false true Controls whether the current SHIR should be auto-updated. Yes

Create

Create a new SHIR resource.

./irctl create [flags]
Flag Parameter type Description
-c,--context string Name of the Kubernetes context to use, if not specified, current context of Kube config will be used
-h,--help Help for create
-r,--registration-key string Key to register SHIR
-s,--selector string Node selector (label query) to filter on, supports '='. (for example,--selector key1=value1,key2=value2) Select nodes by given labels for SHIR to run on. Default is empty, which means SHIR will run on all nodes.

Example:

./irctl create --registration-key 1234@keyvalue

Upgrade

Upgrade an SHIR to the same version with IRCTL.

./irctl upgrade [flags]
./irctl upgrade [command]
Command Description
status Monitors the status the latest SHIR upgrade.
Flag Parameter type Description
-c,--context string Name of the Kubernetes context to use, if not specified, current context of Kube config will be used
-h,--help Help for upgrade

Delete

Delete an SHIR resource.

./irctl delete [flags]
Flag Parameter type Description
-c,--context string Name of the Kubernetes context to use, if not specified, current context of Kube config will be used
-h,--help Help for delete

Describe

Describe SHIR running on the Kubernetes cluster.

./irctl describe [flags]
Flag Parameter type Description
-c,--context string Name of the Kubernetes context to use, if not specified, current context of Kube config will be used
-h,--help Help for describe

Storage

Manage files in SHIR shared storage.

./irctl storage [flags]
./irctl storage [command]
Command Description
upload Upload files to SHIR shared storage.
list List files in SHIR shared storage.
delete Delete files in SHIR shared storage.
Flag Parameter type Description
-h,--help Help for storage

Storage upload

Upload files to SHIR shared storage.

./irctl storage upload -s <source> -d <destination> [flags]
Flag Parameter type Description
-c,--context string Name of the Kubernetes context to use, if not specified, current context of Kube config will be used.
-d,--destination string string Path to store file/folder uploaded in SHIR shared storage.
-h,--help Help for delete
-s,--source string Path to the file/folder to be uploaded.

Storage list

List files in SHIR shared storage.

./irctl storage list <path> [flags]
Flag Parameter type Description
-c,--context string Name of the Kubernetes context to use, if not specified, current context of Kube config will be used.
-h,--help Help for list.

Storage delete

Delete files in SHIR shared storage.

./irctl storage delete <path> [flags]
Flag Parameter type Description
-c,--context string Name of the Kubernetes context to use, if not specified, current context of Kube config will be used.
-h,--help Help for delete.

Log

Log operations from SHIR.

./irctl log [flags]
./irctl log [command]
Command Description
upload Upload logs from SHIR.
download Download logs from SHIR.
Flag Parameter type Description
-h,--help Help for log.

Log upload

Upload logs from SHIR.

./irctl log upload [flags]
./irctl log upload [command]
Command Description
Status Monitors the status of SHIR log uploading.
Flag Parameter type Description
-c,--context string Name of the Kubernetes context to use, if not specified, current context of Kube config will be used.
-h,--help Help for upload.

Log download

Upload logs from SHIR.

./irctl log download [flags]
Flag Parameter type Description
-c,--context string Name of the Kubernetes context to use, if not specified, current context of Kube config will be used.
-d,--destination string Local path to store logs downloaded from SHIR.
-h,--help Help for download.

Next Steps