Skip to content

Commit f54aed2

Browse files
MikeRayMSFTMikeRayMSFT
authored
Merge pull request #182999 from MicrosoftDocs/release-arc-data
Publish Arc Data August release
2 parents f7ca038 + 21f5543 commit f54aed2

14 files changed

+760
-18
lines changed

‎articles/azure-arc/data/active-directory-introduction.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: Introduction to Azure Arc-enabled data services with Active Directory authentication
3+
description: Introduction to Azure Arc-enabled data services with Active Directory authentication
4+
services: azure-arc
5+
ms.service: azure-arc
6+
ms.subservice: azure-arc-data
7+
author: cloudmelon
8+
ms.author: melqin
9+
ms.reviewer: mikeray
10+
ms.date: 12/15/2021
11+
ms.topic: how-to
12+
---
13+
14+
# Introduction to Azure Arc-enabled SQL Managed Instance with Active Directory authentication
15+
16+
This article describes Azure Arc-enabled SQL Managed Instance with Active Directory (AD) Authentication by bring your own keytab (BYOK) where the user is expected to provide a pre-created Active Directory account, Service Principal Names and Keytab.
17+
18+
## Background
19+
20+
In order to support Active Directory authentication for SQL Managed Instance, a SQL Managed Instance must be deployed in an environment that allows it to communicate with the Active Directory domain.
21+
To facilitate this, Azure Arc introduces a new Kubernetes-native [custom resource definition (CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) called `Active Directory Connector`. You can specify this kind of resource in the CRD. An Active Directory Connector custom resource stores the information needed to enable connections to DNS and AD for purposes of authenticating users and service accounts.
22+
23+
This custom resource deploys a DNS proxy service that mediates between the SQL Managed Instance DNS resolver and the two upstream DNS servers:
24+
25+
1. Kubernetes DNS servers
26+
2. Active Directory DNS servers
27+
28+
When a SQL Managed Instance is deployed with Active Directory Authentication enabled, it will reference the Active Directory Connector instance it wants to use. Referencing the Active Directory Connector in SQL MI spec will automatically set up the needed environment in the SQL Managed Instance container for SQL MI to perform Active Directory authentication.
29+
30+
## Active Directory Connector and SQL Managed Instance
31+
32+
![Actice Directory Connector](media/active-directory-deployment/active-directory-connector-byok.png)
33+
34+
## Bring Your Own Keytab (BYOK)
35+
36+
The following are the steps for user to set up:
37+
38+
1. Creating and providing an Active Directory account for each SQL Managed Instance that must accept AD authentication.
39+
1. Providing a DNS name belonging to the Active Directory DNS domain for the SQL Managed Instance endpoint.
40+
1. Creating a DNS record in Active Directory for the SQL endpoint.
41+
1. Providing a port number for the SQL Managed Instance endpoint.
42+
1. Registering Service Principal Names (SPNs) under the AD account in Active Directory domain for the SQL endpoint.
43+
1. Creating and providing a keytab file for SQL Managed Instance containing entries for the AD account and SPNs.
44+
45+
## Next steps
46+
47+
* [Deploy Active Directory (AD) connector](deploy-active-directory-connector.md)
48+
* [Deploy Azure Arc-enabled SQL Managed Instance in Active Directory (AD)](deploy-active-directory-sql-managed-instance.md)
49+
* [Connect to AD-integrated Azure Arc-enabled SQL Managed Instance](connect-active-directory-sql-managed-instance.md)

‎articles/azure-arc/data/connect-active-directory-sql-managed-instance.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
title: Connect to AD-integrated Azure Arc-enabled SQL Managed Instance
3+
description: Connect to AD-integrated Azure Arc-enabled SQL Managed Instance
4+
services: azure-arc
5+
ms.service: azure-arc
6+
ms.subservice: azure-arc-data
7+
author: cloudmelon
8+
ms.author: melqin
9+
ms.reviewer: mikeray
10+
ms.date: 12/15/2021
11+
ms.topic: how-to
12+
---
13+
14+
# Connect to AD-integrated Azure Arc-enabled SQL Managed Instance
15+
16+
This article describes how to connect to SQL Managed Instance endpoint using Active Directory (AD) authentication. Before you proceed, make sure you have an AD-integrated Azure Arc-enabled SQL Managed Instance deployed already.
17+
18+
See [Tutorial – Deploy AD-integrated SQL Managed Instance (Bring Your Own Keytab)](deploy-active-directory-sql-managed-instance.md) to deploy a Azure Arc-enabled SQL Managed Instance with Active Directory (AD) Authentication enabled.
19+
20+
## Create Active Directory logins in SQL Managed Instance
21+
22+
Once SQL Managed Instance is successfully deployed, you will need to provision AD logins in SQL Server.
23+
In order to do this, first connect to the SQL Managed Instance using the SQL login with administrative privileges and run the following TSQL:
24+
25+
```console
26+
CREATE LOGIN [<NetBIOS domain name>\<AD account name>] FROM WINDOWS;
27+
GO
28+
```
29+
30+
For an AD domain `contoso.local` with NetBIOS domain name as `CONTOSO`, if you want to create a login for AD account `admin`, the command should look like the following:
31+
32+
```console
33+
CREATE LOGIN [CONTOSO\admin] FROM WINDOWS;
34+
GO
35+
```
36+
37+
## Connect to Azure Arc-enabled SQL Managed Instance
38+
39+
From your domain joined Windows-based client machine or a Linux-based domain aware machine, you can use `sqlcmd` utility, or open [SQL Server Management Studio](/sql/ssms/download-sql-server-management-studio-ssms) or [Azure Data Studio (ADS)](/sql/azure-data-studio/download-azure-data-studio) to connect to the Azure Arc-enabled SQL Managed Instance using AD authentication.
40+
41+
A domain-aware Linux-based machine is one where you are able to use Kerberos authentication using kinit. Such machine should have /etc/krb5.conf file set to point to the Active Directory domain (realm) being used. It should also have /etc/resolv.conf file set such that one can run DNS lookups against the Active Directory domain.
42+
43+
44+
### Connect from Linux/Mac OS
45+
46+
To connect from a Linux/Mac OS client, authenticate to Active Directory using the kinit command and then use sqlcmd tool to connect to the SQL Managed Instance.
47+
48+
```bash
49+
kinit <username>@<REALM>
50+
sqlcmd -S <Endpoint DNS name>,<Endpoint port number> -E
51+
```
52+
53+
For connecting using the CONTOSO\admin AD account to the SQL Managed Instance with endpoint sqlmi.contoso.local at port 31433, the commands should look like the following. The -E argument is used to perform Integrated Authentication.
54+
55+
```bash
56+
kinit [email protected]
57+
sqlcmd -S sqlmi.contoso.local,31433 -E
58+
```
59+
60+
## Connect to SQL MI instance from Windows
61+
62+
From Windows, when you run the following command, the AD identity you are logged in to Windows with should be picked up automatically for connecting to SQL Managed Instance.
63+
64+
```bash
65+
sqlcmd -S <DNS name for master instance>,31433 -E
66+
```
67+
68+
## Connect to SQL MI instance from SSMS
69+
70+
![Connect with SSMS](media/active-directory-deployment/connect-with-ssms.png)
71+
72+
## Connect to SQL MI instance from ADS
73+
74+
![Connect with ADS](media/active-directory-deployment/connect-with-ads.png)

‎articles/azure-arc/data/create-data-controller-using-kubernetes-native-tools.md

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -216,15 +216,21 @@ First, create a copy of the [template file](https://raw.githubusercontent.com/mi
216216

217217
Edit the following as needed:
218218

219-
**REQUIRED**
220-
- **location**: Change this to be the Azure location where the _metadata_ about the data controller will be stored. Review the [list of available regions](overview.md#supported-regions).
221-
- **resourceGroup**: the Azure resource group where you want to create the data controller Azure resource in Azure Resource Manager. Typically this resource group should already exist, but it is not required until the time that you upload the data to Azure.
222-
- **subscription**: the Azure subscription GUID for the subscription that you want to create the Azure resources in.
223-
224-
**RECOMMENDED TO REVIEW AND POSSIBLY CHANGE DEFAULTS**
225-
- **storage..className**: the storage class to use for the data controller data and log files. If you are unsure of the available storage classes in your Kubernetes cluster, you can run the following command: `kubectl get storageclass`. The default is `default` which assumes there is a storage class that exists and is named `default` not that there is a storage class that _is_ the default. Note: There are two className settings to be set to the desired storage class - one for data and one for logs.
226-
- **serviceType**: Change the service type to `NodePort` if you are not using a LoadBalancer.
227-
- **Security** For Azure Red Hat OpenShift or Red Hat OpenShift Container Platform, replace the `security:` settings with the following values in the data controller yaml file.
219+
- **Required**
220+
- **location**
221+
Change this to be the Azure location where the _metadata_ about the data controller will be stored. Review the [list of available regions](overview.md#supported-regions).
222+
- **resourceGroup**
223+
The Azure resource group where you want to create the data controller Azure resource in Azure Resource Manager. Typically this resource group should already exist, but it is not required until the time that you upload the data to Azure.
224+
- **subscription**
225+
The Azure subscription GUID for the subscription that you want to create the Azure resources in.
226+
227+
- **Recommend review and possibly change default values**
228+
- **storage..className**
229+
The storage class to use for the data controller data and log files. If you are unsure of the available storage classes in your Kubernetes cluster, you can run the following command: `kubectl get storageclass`. The default is `default` which assumes there is a storage class that exists and is named `default` not that there is a storage class that _is_ the default. Note: There are two className settings to be set to the desired storage class - one for data and one for logs.
230+
- **serviceType**
231+
Change the service type to `NodePort` if you are not using a LoadBalancer.
232+
- **Security**
233+
For Azure Red Hat OpenShift or Red Hat OpenShift Container Platform, replace the `security:` settings with the following values in the data controller yaml file.
228234

229235
```yml
230236
security:

‎articles/azure-arc/data/deploy-active-directory-connector.md

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
title: Tutorial – Deploy Active Directory Connector
3+
description: Tutorial to deploy Active Directory Connector
4+
services: azure-arc
5+
ms.service: azure-arc
6+
ms.subservice: azure-arc-data
7+
author: cloudmelon
8+
ms.author: melqin
9+
ms.reviewer: mikeray
10+
ms.date: 12/10/2021
11+
ms.topic: how-to
12+
---
13+
14+
15+
# Tutorial – Deploy Active Directory Connector
16+
17+
This article explains how to deploy Active Directory Connector Custom Resource.
18+
19+
## What is an Active Directory (AD) connector?
20+
21+
The Active Directory (AD) connector is a Kubernetes native custom resource definition (CRD) that allows you to provide
22+
SQL Managed Instances running on the same Data Controller an ability to perform Active Directory Authentication.
23+
24+
An Active Directory Connector instance deploys a DNS proxy service that proxies the DNS requests
25+
coming from the SQL Managed Instance to either of the two upstream DNS services:
26+
* Active Directory DNS Servers
27+
* Kubernetes DNS Servers
28+
29+
## Prerequisites
30+
31+
Before you proceed, you must have:
32+
33+
* An instance of Data Controller deployed on a supported version of Kubernetes
34+
* An Active Directory domain
35+
36+
## Input for deploying Active Directory (AD) Connector
37+
38+
To deploy an instance of Active Directory Connector, several inputs are needed from the Active Directory domain environment.
39+
These inputs are provided in a YAML spec of AD Connector instance.
40+
41+
Following metadata about the AD domain must be available before deploying an instance of AD Connector:
42+
* Name of the Active Directory domain
43+
* List of the domain controllers (fully-qualified domain names)
44+
* List of the DNS server IP addresses
45+
46+
Following input fields are exposed to the users in the Active Directory Connector spec:
47+
48+
- **Required**
49+
- **spec.activeDirectory.realm**
50+
Name of the Active Directory domain in uppercase. This is the AD domain that this instance of AD Connector will be associated with.
51+
52+
- **spec.activeDirectory.domainControllers.primaryDomainController.hostname**
53+
Fully-qualified domain name of the Primary Domain Controller (PDC) in the AD domain.
54+
55+
If you do not know which domain controller in the domain is primary, you can find out by running this command on any Windows machine joined to the AD domain: `netdom query fsmo`.
56+
57+
- **spec.activeDirectory.dns.nameserverIpAddresses**
58+
List of Active Directory DNS server IP addresses. DNS proxy service will forward DNS queries in the provided domain name to these servers.
59+
60+
61+
- **Optional**
62+
- **spec.activeDirectory.netbiosDomainName**
63+
NETBIOS name of the Active Directory domain. This is the short domain name that represents the Active Directory domain.
64+
65+
This is often used to qualify accounts in the AD domain. e.g. if the accounts in the domain are referred to as CONTOSO\admin, then CONTOSO is the NETBIOS domain name.
66+
67+
This field is optional. When not provided, it defaults to the first label of the `spec.activeDirectory.realm` field.
68+
69+
In most domain environments, this is set to the default value but some domain environments may have a non-default value.
70+
71+
- **spec.activeDirectory.domainControllers.secondaryDomainControllers[*].hostname**
72+
List of the fully-qualified domain names of the secondary domain controllers in the AD domain.
73+
74+
If your domain is served by multiple domain controllers, it is a good practice to provide some of their fully-qualified domain names in this list. This allows high-availability for Kerberos operations.
75+
76+
This field is optional and not needed if your domain is served by only one domain controller.
77+
78+
- **spec.activeDirectory.dns.domainName**
79+
DNS domain name for which DNS lookups should be forwarded to the Active Directory DNS servers.
80+
81+
A DNS lookup for any name belonging to this domain or its descendant domains will get forwarded to Active Directory.
82+
83+
This field is optional. When not provided, it defaults to the value provided for `spec.activeDirectory.realm` converted to lowercase.
84+
85+
- **spec.activeDirectory.dns.replicas**
86+
Replica count for DNS proxy service. This field is optional and defaults to 1 when not provided.
87+
88+
- **spec.activeDirectory.dns.preferK8sDnsForPtrLookups**
89+
Flag indicating whether to prefer Kubernetes DNS server response over AD DNS server response for IP address lookups.
90+
91+
DNS proxy service relies on this field to determine which upstream group of DNS servers to prefer for IP address lookups.
92+
93+
This field is optional. When not provided, it defaults to true i.e. the DNS lookups of IP addresses will be first forwarded to Kubernetes DNS servers.
94+
95+
If Kubernetes DNS servers fail to answer the lookup, the query is then forwarded to AD DNS servers.
96+
97+
98+
## Deploy Active Directory (AD) connector
99+
To deploy an AD connector, create a YAML spec file called `active-directory-connector.yaml`.
100+
The following example uses an AD domain of name `CONTOSO.LOCAL`. Ensure to replace the values with the ones for your AD domain.
101+
102+
```yaml
103+
apiVersion: arcdata.microsoft.com/v1beta1
104+
kind: ActiveDirectoryConnector
105+
metadata:
106+
name: adarc
107+
namespace: <namespace>
108+
spec:
109+
activeDirectory:
110+
realm: CONTOSO.LOCAL
111+
domainControllers:
112+
primaryDomainController:
113+
hostname: dc1.contoso.local
114+
secondaryDomainControllers:
115+
- hostname: dc2.contoso.local
116+
- hostname: dc3.contoso.local
117+
dns:
118+
preferK8sDnsForPtrLookups: false
119+
nameserverIPAddresses:
120+
- <DNS Server 1 IP address>
121+
- <DNS Server 2 IP address>
122+
```
123+
124+
The following command deploys the AD connector instance. Currently, only kube-native approach of deploying is supported.
125+
126+
```console
127+
kubectl apply –f active-directory-connector.yaml
128+
```
129+
130+
After submitting the deployment of AD Connector instance, you may check the status of the deployment using the following command.
131+
132+
```console
133+
kubectl get adc -n <namespace>
134+
```
135+
136+
## Next steps
137+
138+
* [Deploy SQL Managed Instance with Active Directory Authentication](deploy-active-directory-sql-managed-instance.md).
139+
* [Connect to AD-integrated Azure Arc-enabled SQL Managed Instance](connect-active-directory-sql-managed-instance.md).
140+

0 commit comments

Comments
 (0)