az sql mi-arc

Note

This reference is part of the arcdata extension for the Azure CLI (version 2.3.1 or higher). The extension will automatically install the first time you run an az sql mi-arc command. Learn more about extensions.

Manage Azure Arc-enabled SQL managed instances.

Commands

az sql mi-arc config

Configuration commands.

az sql mi-arc config add

Add a value for a json path in a config file.

az sql mi-arc config init

Initialize the CRD and specification files for a SQL managed instance.

az sql mi-arc config patch

Patch a config file based on a json patch file.

az sql mi-arc config remove

Remove a value for a json path in a config file.

az sql mi-arc config replace

Replace a value for a json path in a config file.

az sql mi-arc create

Create a SQL managed instance.

az sql mi-arc delete

Delete a SQL managed instance.

az sql mi-arc edit

Deprecated, use update over edit.

az sql mi-arc endpoint

View and manage SQL endpoints.

az sql mi-arc endpoint list

List the SQL endpoints.

az sql mi-arc get-mirroring-cert

Retrieve certificate of availability group mirroring endpoint from sql mi and store in a file.

az sql mi-arc list

List SQL managed instances.

az sql mi-arc reprovision-replica

Reprovision a replica in a SQL managed instance.

az sql mi-arc show

Show the details of a SQL managed instance.

az sql mi-arc update

Update the configuration of a SQL managed instance.

az sql mi-arc upgrade

Upgrade SQL managed instance.

az sql mi-arc create

Create a SQL managed instance.

To set the password of the SQL managed instance, set the environment variable AZDATA_PASSWORD.

az sql mi-arc create --name
                     [--ad-account-name]
                     [--ad-connector-name]
                     [--ad-encryption-types]
                     [--admin-login-secret]
                     [--agent-enabled]
                     [--annotations]
                     [--cert-private-key-file]
                     [--cert-public-key-file]
                     [--collation]
                     [--cores-limit]
                     [--cores-request]
                     [--custom-location]
                     [--dev]
                     [--k8s-namespace]
                     [--keytab-secret]
                     [--labels]
                     [--language]
                     [--license-type]
                     [--memory-limit]
                     [--memory-request]
                     [--no-external-endpoint]
                     [--no-wait]
                     [--orchestrator-replicas]
                     [--path]
                     [--primary-dns-name]
                     [--primary-port-number]
                     [--readable-secondaries]
                     [--replicas {1, 2, 3}]
                     [--resource-group]
                     [--retention-days]
                     [--secondary-dns-name]
                     [--secondary-port-number]
                     [--service-annotations]
                     [--service-cert-secret]
                     [--service-labels]
                     [--service-type {LoadBalancer, NodePort}]
                     [--storage-annotations]
                     [--storage-class-backups]
                     [--storage-class-data]
                     [--storage-class-datalogs]
                     [--storage-class-logs]
                     [--storage-class-orchestrator-logs]
                     [--storage-labels]
                     [--sync-secondary-to-commit {-1, 0, 1, 2}]
                     [--tier]
                     [--time-zone]
                     [--trace-flags]
                     [--use-k8s]
                     [--volume-size-backups]
                     [--volume-size-data]
                     [--volume-size-datalogs]
                     [--volume-size-logs]
                     [--volume-size-orchestrator-logs]

Examples

Create a SQL managed instance through the Kubernetes API.

az sql mi-arc create -n sqlmi1 --k8s-namespace arc --use-k8s

Create a SQL managed instance with 3 replicas in HA scenario through the Kubernetes API.

az sql mi-arc create -n sqlmi2 --replicas 3 --k8s-namespace arc --use-k8s

Create a SQL managed instance through Azure Resource Manager (ARM).

az sql mi-arc create --name sqlmi3 --resource-group rg-name --custom-location arc-cl

Create a SQL managed instance with Active Directory authentication through the Kubernetes API.

az sql mi-arc create --name contososqlmi --k8s-namespace arc --ad-connector-name arcadc --ad-account-name arcuser --keytab-secret arcuser-keytab-secret --primary-dns-name contososqlmi-primary.contoso.local --primary-port-number 8143 --use-k8s

Required Parameters

--name -n

The name of the SQL managed instance.

Optional Parameters

--ad-account-name

The Active Directory account name for this Arc-enabled SQL Managed Instance. This account needs to be created prior to the deployment of this instance.

--ad-connector-name

The name of the Active Directory Connector. This parameter indicates an intent to deploy with AD support.

--ad-encryption-types

A comma-separated list of supported Active Directory encryption types. Must be a subset of the following values: RC4, AES128, AES256.

--admin-login-secret

Name of the Kubernetes secret to generate that hosts or will host user admin login account credential.

--agent-enabled

Enable SQL Server agent for the instance. Default is disabled. Allowed values are 'true' or 'false'.

--annotations

Comma-separated list of annotations of the SQL managed instance.

--cert-private-key-file

Path to the file containing a PEM formatted certificate private key to be used for SQL Server.

--cert-public-key-file

Path to the file containing a PEM formatted certificate public key to be used for SQL Server.

--collation

The SQL Server collation for the instance.

--cores-limit -c

The cores limit of the managed instance as an integer.

--cores-request

The request for cores of the managed instance as an integer.

--custom-location

The custom location for this instance.

--dev

If this is specified, then it is considered a dev instance and will not be billed for.

--k8s-namespace -k

Namespace where the SQL managed instance is to be deployed. If no namespace is specified, then the namespace defined in the kubeconfig will be used.

--keytab-secret

The name of the Kubernetes secret that contains the keytab file for this Arc-enabled SQL Managed Instance.

--labels

Comma-separated list of labels of the SQL managed instance.

--language

The SQL Server locale to any supported language identifier (LCID) for the instance.

--license-type -l

The license type to apply for this managed instance Allowed values are: BasePrice, LicenseIncluded, DisasterRecovery.Default is LicenseIncluded. The license type can be changed..

--memory-limit -m

The limit of the capacity of the managed instance as an integer number followed by Gi (gigabytes). Example: 4Gi.

--memory-request

The request for the capacity of the managed instance as an integer number followed by Gi (gigabytes). Example: 4Gi.

--no-external-endpoint

If specified, no external service will be created. Otherwise, an external service will be created using the same service type as the data controller.

--no-wait

Do not wait for the long-running operation to finish.

--orchestrator-replicas

The number of high availability orchestrator replicas. Value must be between 1 and 3.

--path

The path to the azext_arcdata file for the SQL managed instance json file.

--primary-dns-name

The primary service DNS name exposed to the end-users to connect to this Arc-enabled SQL Managed Instance (e.g. sqlinstancename.contoso.com).

--primary-port-number

The port number on which the primary service is exposed to the end-users (e.g. 31433).

--readable-secondaries

Number of replicas to be made readable. Applies only to Business Critical tier. Value must be between 0 and the number of replicas minus 1.

--replicas

This option specifies the number of SQL Managed Instance replicas that will be deployed in your Kubernetes cluster for high availability purposes. Default is 1 replica for General Purpose, 3 replicas for Business Critical.

accepted values: 1, 2, 3
--resource-group -g

The Azure resource group to which the Arc-enabled SQL Managed Instance should be added.

--retention-days

Backup retention period, specified in days. Allowed values are 0 to 35. Default is 7. Setting the retention period to 0 will turn off automatic backups for all the databases on the SQL managed instance and any prior backups will be deleted.

--secondary-dns-name

The secondary service DNS name exposed to the end-users to connect to this Arc-enabled SQL Managed Instance (e.g. sqlinstancename2.contoso.com).

--secondary-port-number

The port number on which the secondary service is exposed to the end-users (e.g. 31434).

--service-annotations

Comma-separated list of annotations to apply to all external services.

--service-cert-secret

Name of the Kubernetes secret to generate that hosts or will host SQL service certificate.

--service-labels

Comma-separated list of labels to apply to all external services.

--service-type

The type for the primary service.

accepted values: LoadBalancer, NodePort
--storage-annotations

Comma-separated list of annotations to apply to all PVCs.

--storage-class-backups

A ReadWriteMany (RWX) capable storage class to be used for backups (/var/opt/mssql/backups). If no value is specified, the default storage class will be used.

--storage-class-data -d

The storage class to be used for data files (.mdf, .ndf). If no value is specified, then no storage class will be specified, which will result in Kubernetes using the default storage class.

--storage-class-datalogs

The storage class to be used for database logs (.ldf). If no value is specified, then no storage class will be specified, which will result in Kubernetes using the default storage class.

--storage-class-logs

The storage class to be used for logs (/var/log). If no value is specified, then no storage class will be specified, which will result in Kubernetes using the default storage class.

--storage-class-orchestrator-logs

The storage class to be used for orchestrator logs (/var/log). If no value is specified, then no storage class will be specified, which will result in Kubernetes using the default storage class.

--storage-labels

Comma-separated list of labels to apply to all PVCs.

--sync-secondary-to-commit

Number of secondary replicas that must be synchronized to commit. Setting this value to -1 will set the number of required synchronized secondaries to '(# of replicas - 1) / 2', rounded down.

accepted values: -1, 0, 1, 2
default value: -1
--tier -t

The pricing tier for the instance. Allowed values: BusinessCritical (bc for short) or GeneralPurpose (gp for short). Default is GeneralPurpose. The price tier cannot be changed.

--time-zone

The SQL Server time zone for the instance.

--trace-flags

Comma separated list of traceflags. No flags by default.

--use-k8s

Create SQL managed instance using local Kubernetes APIs.

--volume-size-backups

The size of the storage volume to be used for backups as a positive number followed by Ki (kilobytes), Mi (megabytes), or Gi (gigabytes).

--volume-size-data

The size of the storage volume to be used for data as a positive number followed by Ki (kilobytes), Mi (megabytes), or Gi (gigabytes).

--volume-size-datalogs

The size of the storage volume to be used for data logs as a positive number followed by Ki (kilobytes), Mi (megabytes), or Gi (gigabytes).

--volume-size-logs

The size of the storage volume to be used for logs as a positive number followed by Ki (kilobytes), Mi (megabytes), or Gi (gigabytes).

--volume-size-orchestrator-logs

The size of the storage volume to be used for orchestrator logs as a positive number followed by Ki (kilobytes), Mi (megabytes), or Gi (gigabytes).

az sql mi-arc delete

Delete a SQL managed instance.

az sql mi-arc delete --name
                     [--k8s-namespace]
                     [--no-wait]
                     [--resource-group]
                     [--use-k8s]

Examples

Delete a SQL managed instance through the Kubernetes API.

az sql mi-arc delete --name sqlmi1 --k8s-namespace arc --use-k8s

Delete a SQL managed instance through Azure Resource Manager (ARM).

az sql mi-arc delete --name sqlmi1 --resource-group rg-name

Required Parameters

--name -n

The name of the SQL managed instance to be deleted.

Optional Parameters

--k8s-namespace -k

Namespace where the SQL managed instance is to be deployed. If no namespace is specified, then the namespace defined in the kubeconfig will be used.

--no-wait

Do not wait for the long-running operation to finish.

--resource-group -g

The Azure resource group in which the Arc-enabled SQL Managed Instance exists.

--use-k8s

Use local Kubernetes APIs to perform this action.

az sql mi-arc edit

Deprecated, use update over edit.

az sql mi-arc edit --name
                   [--agent-enabled]
                   [--annotations]
                   [--cores-limit]
                   [--cores-request]
                   [--custom-location]
                   [--dev]
                   [--k8s-namespace]
                   [--labels]
                   [--license-type]
                   [--location]
                   [--memory-limit]
                   [--memory-request]
                   [--no-wait]
                   [--path]
                   [--resource-group]
                   [--retention-days]
                   [--service-annotations]
                   [--service-labels]
                   [--tag-name]
                   [--tag-value]
                   [--tier]
                   [--time-zone]
                   [--trace-flags]
                   [--use-k8s]

Required Parameters

--name -n

The name of the SQL managed instance that is being edited. The name under which your instance is deployed cannot be changed.

Optional Parameters

--agent-enabled

Enable SQL Server agent for the instance. Default is disabled.

--annotations

Comma-separated list of annotations of the SQL managed instance.

--cores-limit -c

The cores limit of the managed instance as an integer.

--cores-request

The request for cores of the managed instance as an integer.

--custom-location

The custom location for this instance.

--dev

If this is specified, then it is considered a dev instance and will not be billed for.

--k8s-namespace -k

Namespace where the SQL managed instance is to be deployed. If no namespace is specified, then the namespace defined in the kubeconfig will be used.

--labels

Comma-separated list of labels of the SQL managed instance.

--license-type

The license type to update for this managed instance Allowed values are: BasePrice, LicenseIncluded, DisasterRecovery. Default is LicenseIncluded.

--location

The Azure location in which the sqlmi metadata will be stored (e.g. eastus).

--memory-limit -m

The limit of the capacity of the managed instance as an integer number followed by Gi (gigabytes). Example: 4Gi.

--memory-request

The request for the capacity of the managed instance as an integer number followed by Gi (gigabytes). Example: 4Gi.

--no-wait

If given, the command will not wait for the instance to be in a ready state before returning.

--path

The path to the azext_arcdata file for the SQL managed instance json file.

--resource-group -g

The Azure resource group in which the Arc-enabled SQL Managed Instance exists.

--retention-days

Backup retention period, specified in days. Allowed values are 0 to 35. Default is 7. Setting the retention period to 0 will turn off automatic backups for all the databases on the SQL managed instance and any prior backups will be deleted.

--service-annotations

Comma-separated list of annotations to apply to all external services.

--service-labels

Comma-separated list of labels to apply to all external services.

--tag-name

The tag name of the SQL managed instance.

--tag-value

The tag value of the SQL managed instance.

--tier -t

The pricing tier for the instance. Allowed values: BusinessCritical (bc for short) or GeneralPurpose (gp for short). Default is GeneralPurpose. The price tier cannot be changed.

--time-zone

The SQL Server time zone for the instance.

--trace-flags

Comma separated list of traceflags. No flags by default.

--use-k8s

Use local Kubernetes APIs to perform this action.

az sql mi-arc get-mirroring-cert

Retrieve certificate of availability group mirroring endpoint from sql mi and store in a file.

az sql mi-arc get-mirroring-cert --cert-file
                                 --name
                                 [--k8s-namespace]
                                 [--use-k8s]

Examples

Retrieve certificate of availability group mirroring endpoint from sqlmi1 and store in file fileName1

az sql mi-arc get-mirroring-cert -n sqlmi1 --cert-file fileName1

Required Parameters

--cert-file

The local filename to store the retrieved certificate in PEM format.

--name -n

The name of the SQL managed instance.

Optional Parameters

--k8s-namespace -k

Namespace where the SQL managed instance is to be deployed. If no namespace is specified, then the namespace defined in the kubeconfig will be used.

--use-k8s

Use local Kubernetes APIs to perform this action.

az sql mi-arc list

List SQL managed instances.

az sql mi-arc list [--custom-location]
                   [--k8s-namespace]
                   [--resource-group]
                   [--use-k8s]

Examples

List SQL managed instances.

az sql mi-arc list --use-k8s

Optional Parameters

--custom-location

The custom location in which the Arc-enabled SQL Managed Instances are deployed. If not specified, all instances in the resource group will be listed.

--k8s-namespace -k

The Kubernetes namespace containing the Arc-enabled SQL Managed Instances. If no namespace is specified, then the namespace defined in the kubeconfig will be used.

--resource-group -g

The Azure resource group containing the Arc-enabled SQL Managed Instances.

--use-k8s

Use local Kubernetes APIs to perform this action.

az sql mi-arc reprovision-replica

Reprovision a replica in a SQL managed instance.

az sql mi-arc reprovision-replica --name
                                  [--k8s-namespace]
                                  [--no-wait]
                                  [--use-k8s]

Examples

Ex 1 - Reprovision replica 1 of SQL managed instance sqlmi1.

az sql mi-arc reprovision-replica -n sqlmi1-1 --use-k8s --k8s-namespace namespace

Required Parameters

--name -n

The name of the SQL managed instance replica to be reprovisioned.

Optional Parameters

--k8s-namespace -k

Namespace where the SQL managed instance replica is deployed. If no namespace is specified, then the namespace defined in the kubeconfig will be used.

--no-wait

Do not wait for the long-running operation to finish.

--use-k8s

Reprovision SQL managed instance replica using local Kubernetes APIs.

az sql mi-arc show

Show the details of a SQL managed instance.

az sql mi-arc show --name
                   [--k8s-namespace]
                   [--path]
                   [--resource-group]
                   [--use-k8s]

Examples

Show the details of a SQL Managed Instance using the Kubernetes API.

az sql mi-arc show --name sqlmi1 --k8s-namespace arc --use-k8s

Show the details of a SQL Managed Instance by querying Azure Resource Manager (ARM).

az sql mi-arc show --name sqlmi1 --resource-group rg-name

Required Parameters

--name -n

The name of the SQL managed instance to be shown.

Optional Parameters

--k8s-namespace -k

Namespace where the SQL managed instance is to be deployed. If no namespace is specified, then the namespace defined in the kubeconfig will be used.

--path -p

A path where the full specification for the SQL managed instance should be written. If omitted, the specification will be written to standard output.

--resource-group -g

The Azure resource group in which the Arc-enabled SQL Managed Instance exists.

--use-k8s

Use local Kubernetes APIs to perform this action.

az sql mi-arc update

Update the configuration of a SQL managed instance.

az sql mi-arc update --name
                     [--ad-encryption-types]
                     [--agent-enabled]
                     [--annotations]
                     [--cert-private-key-file]
                     [--cert-public-key-file]
                     [--cores-limit]
                     [--cores-request]
                     [--k8s-namespace]
                     [--keytab-secret]
                     [--labels]
                     [--license-type]
                     [--memory-limit]
                     [--memory-request]
                     [--no-wait]
                     [--orchestrator-replicas]
                     [--path]
                     [--preferred-primary-replica]
                     [--readable-secondaries]
                     [--replicas {1, 2, 3}]
                     [--resource-group]
                     [--retention-days]
                     [--service-annotations]
                     [--service-cert-secret]
                     [--service-labels]
                     [--sync-secondary-to-commit {-1, 0, 1, 2}]
                     [--tier]
                     [--time-zone]
                     [--trace-flags]
                     [--use-k8s]

Examples

Update the configuration of a SQL managed instance.

az sql mi-arc update --path ./spec.json -n sqlmi1 --use-k8s

Required Parameters

--name -n

The name of the SQL managed instance that is being edited. The name under which your instance is deployed cannot be changed.

Optional Parameters

--ad-encryption-types

A comma-separated list of supported Active Directory encryption types. Must be a subset of the following values: RC4, AES128, AES256.

--agent-enabled

Enable SQL Server agent for the instance. Default is disabled.

--annotations

Comma-separated list of annotations of the SQL managed instance.

--cert-private-key-file

Path to the file containing a PEM formatted certificate private key to be used for SQL Server.

--cert-public-key-file

Path to the file containing a PEM formatted certificate public key to be used for SQL Server.

--cores-limit -c

The cores limit of the managed instance as an integer.

--cores-request

The request for cores of the managed instance as an integer.

--k8s-namespace -k

Namespace where the SQL managed instance is to be deployed. If no namespace is specified, then the namespace defined in the kubeconfig will be used.

--keytab-secret

The name of the Kubernetes secret that contains the keytab file for this Arc-enabled SQL Managed Instance.

--labels

Comma-separated list of labels of the SQL managed instance.

--license-type -l

The license type to apply for this managed instance Allowed values are: BasePrice, LicenseIncluded, DisasterRecovery.Default is LicenseIncluded. The license type can be changed..

--memory-limit -m

The limit of the capacity of the managed instance as an integer number followed by Gi (gigabytes). Example: 4Gi.

--memory-request

The request for the capacity of the managed instance as an integer number followed by Gi (gigabytes). Example: 4Gi.

--no-wait

Do not wait for the long-running operation to finish.

--orchestrator-replicas

The number of high availability orchestrator replicas. Value must be between 1 and 3.

--path

The path to the azext_arcdata file for the SQL managed instance json file.

--preferred-primary-replica

The preferred primary replica to be updated.

--readable-secondaries

Number of replicas to be made readable. Applies only to Business Critical tier. Value must be between 0 and the number of replicas minus 1.

--replicas

This option specifies the number of SQL Managed Instance replicas that will be deployed in your Kubernetes cluster for high availability purposes.

accepted values: 1, 2, 3
--resource-group -g

The Azure resource group in which the Arc-enabled SQL Managed Instance exists.

--retention-days

Backup retention period, specified in days. Allowed values are 0 to 35. Default is 7. Setting the retention period to 0 will turn off automatic backups for all the databases on the SQL managed instance and any prior backups will be deleted.

--service-annotations

Comma-separated list of annotations to apply to all external services.

--service-cert-secret

Name of the Kubernetes secret to generate that hosts or will host SQL service certificate.

--service-labels

Comma-separated list of labels to apply to all external services.

--sync-secondary-to-commit

Number of secondary replicas that must be synchronized to commit. Setting this value to -1 will set the number of required synchronized secondaries to '(# of replicas - 1) / 2', rounded down.

accepted values: -1, 0, 1, 2
--tier -t

The pricing tier for the instance. Allowed values: BusinessCritical (bc for short) or GeneralPurpose (gp for short). Default is GeneralPurpose. The price tier cannot be changed.

--time-zone

The SQL Server time zone for the instance.

--trace-flags

Comma separated list of traceflags. No flags by default.

--use-k8s

Use local Kubernetes APIs to perform this action.

az sql mi-arc upgrade

Upgrade SQL managed instance.

Upgrade SQL managed instance to the desired-version specified. If desired-version is not specified, the data controller version will be used.

az sql mi-arc upgrade [--desired-version]
                      [--dry-run]
                      [--field-filter]
                      [--force]
                      [--k8s-namespace]
                      [--label-filter]
                      [--name]
                      [--no-wait]
                      [--resource-group]
                      [--target]
                      [--use-k8s]

Examples

Upgrade SQL managed instance.

az sql mi-arc upgrade -n sqlmi1 -k arc --desired-version v1.1.0 --use-k8s

Optional Parameters

--desired-version -v

The latest valid version to upgrade to. Optional, if no version is specified, the data controller version will be used. Specify 'auto' to automatically upgrade to the latest valid version. Learn more about automatic upgrades at: https://aka.ms/arc-sqlmi-auto-upgrade.

--dry-run -d

Indicates which instance would be upgraded but does not actually upgrade the instances.

--field-filter -f

Filter to select instances to upgrade based on resource properties.

--force

Overrides all policies that may be applied to the instance, and attempts the upgrade.

--k8s-namespace -k

Namespace where the SQL managed instance is to be deployed. If no namespace is specified, then the namespace defined in the kubeconfig will be used.

--label-filter -l

Filter to select instance to upgrade based on labels.

--name -n

The name of the SQL managed instance.

--no-wait

Do not wait for the long-running operation to finish.

--resource-group -g

The Azure resource group in which the target Arc-enabled SQL Managed Instance exists.

--target

The latest valid version to upgrade to. Optional, if no version is specified, the data controller version will be used. Specify 'auto' to automatically upgrade to the latest valid version. Learn more about automatic upgrades at: https://aka.ms/arc-sqlmi-auto-upgrade.

--use-k8s

Use local Kubernetes APIs to perform this action.