1

installing/installing_azure/ipi/installing-azure-customizations.adoc

@@ -7,13 +7,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-In {product-title} version {product-version}, you can install a cluster with a customized configuration or a customized network configuration on infrastructure that the installation program provisions on {azure-first}.
-
-To install a cluster with customizations or with network customizations, modify parameters in the `install-config.yaml` file before you install the cluster.
-
-By customizing your network configuration, your cluster can coexist with existing IP address allocations in your environment and integrate with existing MTU and VXLAN configurations.
-
-You must set most of the network configuration parameters during installation, and you can modify only the `kubeProxy` configuration parameters in a running cluster.
+[role="_abstract"]
+In {product-title} version {product-version}, you can install a cluster with a customized configuration or a customized network configuration on infrastructure that the installation program provisions on {azure-first}. To install a cluster with customizations or with network customizations, modify parameters in the `install-config.yaml` file before you install the cluster. By customizing your network configuration, your cluster can coexist with existing IP address allocations in your environment and integrate with existing MTU and VXLAN configurations. You must set most of the network configuration parameters during installation, and you can modify only the `kubeProxy` configuration parameters in a running cluster.
 
 include::modules/installation-azure-marketplace-subscribe.adoc[leveloffset=+1]
 
@@ -40,6 +35,8 @@ include::modules/installation-azure-confidential-vms.adoc[leveloffset=+2]
 
 include::modules/installation-azure-dedicated-disks.adoc[leveloffset=+2]
 
+include::modules/installing-azure-managing-dns-solution.adoc[leveloffset=+2]
+
 include::modules/installation-azure-config-yaml.adoc[leveloffset=+2]
 
 include::modules/installation-configure-proxy.adoc[leveloffset=+2]
@@ -103,6 +100,8 @@ include::modules/cco-ccoctl-install-creating-manifests.adoc[leveloffset=+3]
 
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
+include::modules/installing-azure-provisioning-dns-records.adoc[leveloffset=+1]
+
 include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
 
 [role="_additional-resources"]

installing/installing_azure/ipi/installing-azure-private.adoc

@@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-In {product-title} version {product-version}, you can install a private cluster into an existing Azure Virtual Network (VNet) on Microsoft Azure. The installation program provisions the rest of the required infrastructure, which you can further customize. To customize the installation, you modify parameters in the `install-config.yaml` file before you install the cluster.
+[role="_abstract"]
+In {product-title} version {product-version}, you can install a private cluster into an existing {azure-short} Virtual Network (VNet) on {azure-full}. The installation program provisions the rest of the required infrastructure, which you can further customize. To customize the installation, you modify parameters in the `install-config.yaml` file before you install the cluster.
 
 include::modules/private-clusters-default.adoc[leveloffset=+1]
 
@@ -44,6 +45,8 @@ include::modules/installation-azure-trusted-launch.adoc[leveloffset=+2]
 
 include::modules/installation-azure-confidential-vms.adoc[leveloffset=+2]
 
+include::modules/installing-azure-managing-dns-solution.adoc[leveloffset=+2]
+
 include::modules/installation-azure-config-yaml.adoc[leveloffset=+2]
 
 include::modules/installation-configure-proxy.adoc[leveloffset=+2]
@@ -89,6 +92,8 @@ include::modules/installing-private-image-registry-private-azure.adoc[leveloffse
 
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
+include::modules/installing-azure-provisioning-dns-records.adoc[leveloffset=+1]
+
 include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
 
 [role="_additional-resources"]

installing/installing_azure/ipi/installing-azure-vnet.adoc

@@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-In {product-title} version {product-version}, you can install a cluster into an existing Azure Virtual Network (VNet) on Microsoft Azure. The installation program provisions the rest of the required infrastructure, which you can further customize. To customize the installation, you modify parameters in the `install-config.yaml` file before you install the cluster.
+[role="_abstract"]
+In {product-title} version {product-version}, you can install a cluster into an existing {azure-short} Virtual Network (VNet) on {azure-full}. The installation program provisions the rest of the required infrastructure, which you can further customize. To customize the installation, you modify parameters in the `install-config.yaml` file before you install the cluster.
 
 include::modules/installation-about-custom-azure-vnet.adoc[leveloffset=+1]
 
@@ -38,6 +39,8 @@ include::modules/installation-azure-trusted-launch.adoc[leveloffset=+2]
 
 include::modules/installation-azure-confidential-vms.adoc[leveloffset=+2]
 
+include::modules/installing-azure-managing-dns-solution.adoc[leveloffset=+2]
+
 include::modules/installation-azure-config-yaml.adoc[leveloffset=+2]
 
 include::modules/installation-configure-proxy.adoc[leveloffset=+2]
@@ -76,6 +79,8 @@ include::modules/cco-ccoctl-install-creating-manifests.adoc[leveloffset=+3]
 
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
+include::modules/installing-azure-provisioning-dns-records.adoc[leveloffset=+1]
+
 [role="_additional-resources"]
 .Additional resources
 

installing/installing_azure/ipi/installing-restricted-networks-azure-installer-provisioned.adoc

@@ -57,6 +57,8 @@ include::modules/installation-azure-confidential-vms.adoc[leveloffset=+2]
 
 include::modules/installation-azure-dedicated-disks.adoc[leveloffset=+2]
 
+include::modules/installing-azure-managing-dns-solution.adoc[leveloffset=+2]
+
 include::modules/installation-azure-config-yaml.adoc[leveloffset=+2]
 
 include::modules/installation-configure-proxy.adoc[leveloffset=+2]
@@ -90,6 +92,8 @@ include::modules/cco-ccoctl-install-creating-manifests.adoc[leveloffset=+3]
 
 include::modules/installation-launching-installer.adoc[leveloffset=+1]
 
+include::modules/installing-azure-provisioning-dns-records.adoc[leveloffset=+1]
+
 include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
 
 == Next steps

modules/installation-configuration-parameters.adoc

@@ -2435,6 +2435,13 @@ If you specify either the `NATGatewaySingleZone` or the `NATGatewayMultiZone` ro
 
 *Value:* `name` specifies the name of the subnet. Valid `role` values are `node` or `control-plane`.
 
+|platform:
+  azure:
+    userProvisionedDNS:
+|Enables user-provisioned DNS instead of the default cluster-provisioned DNS solution. If you use this feature, you must provide your own DNS solution that includes records for `api.<cluster_name>.<base_domain>.` and `*.apps.<cluster_name>.<base_domain>.`. The default value is `Disabled`. `userProvisionedDNS` is a Technology Preview feature.
+
+*Value:* `Enabled` or `Disabled`. The default value is `Disabled`.
+
 |platform:
   azure:
     zone:

modules/installing-azure-managing-dns-solution.adoc

@@ -0,0 +1,40 @@
+:_mod-docs-content-type: PROCEDURE
+[id="installation-azure-enabling-user-managed-DNS_{context}"]
+= Enabling a user-managed DNS
+
+[role="_abstract"]
+You can install a cluster with a domain name server (DNS) solution that you manage instead of the default cluster-provisioned DNS solution. As a result, you can manage the API and Ingress DNS records in your own system rather than adding the records to the DNS of the cloud. For example, your organization's security policies might not allow the use of public DNS services such as {azure-first}. In such scenarios, you can use your own DNS service to bypass the public DNS service and manage your own DNS for the IP addresses of the API and Ingress services.
+
+If you enable user-managed DNS during installation, the installation program provisions DNS records for the API and Ingress services only within the cluster. To ensure access from outside the cluster, you must provision the DNS records in an external DNS service of your choice for the API and Ingress services after installation.
+
+:FeatureName: User-provisioned DNS
+include::snippets/technology-preview.adoc[leveloffset=+1]
+
+.Prerequisites
+
+* You installed the `jq` package.
+
+.Procedure
+* Before you deploy your cluster, use a text editor to open the `install-config.yaml` file  and add the following stanza:
+** To enable user-managed DNS:
++
+[source,yaml]
+----
+featureSet: CustomNoUpgrade
+featureGates: ["AzureClusterHostedDNSInstall=true"]
+
+# ...
+
+platform:
+  azure:
+    userProvisionedDNS: Enabled
+----
++
+where:
++
+--
+`userProvisionedDNS`:: Enables user-provisioned DNS management.
+--
+
+.Next steps
+For information about provisioning your DNS records for the API server and the Ingress services, see "Provisioning your own DNS records".

modules/installing-azure-provisioning-dns-records.adoc

@@ -0,0 +1,151 @@
+
+:_mod-docs-content-type: PROCEDURE
+[id="installation-azure-provisioning-own-dns-records_{context}"]
+= Provisioning your own DNS records
+
+[role="_abstract"]
+Use the IP address of the API server to provision your own DNS record with the `api.<cluster_name>.<base_domain>.` hostname by using your cluster name and base cluster domain. Use the IP address of the Ingress service to provision your own DNS record with the `*.apps.<cluster_name>.<base_domain>.` hostname by using your cluster name and base cluster domain.
+
+:FeatureName: User-provisioned DNS
+include::snippets/technology-preview.adoc[leveloffset=+1]
+
+
+.Prerequisite
+* You have installed the {azure-short} CLI client `(az)`.
+
+.Procedure
+
+. Add the `userProvisionedDNS` parameter to the `install-config.yaml` file and enable the parameter. For more information, see "Enabling a user-managed DNS".
+
+. Install your cluster.
+
+. If you are installing a private cluster, set the `lb_name` variable by running the following command:
++
+[source,terminal]
+----
+$ lb_name="${infra_id}-internal"
+----
+
+.. Set the `frontendipconfig_id` variable by running the following command:
++
+[source,terminal]
+----
+$ frontendipconfig_id=$(az network lb show -n ${lb_name} -g ${cluster_resource_group_name} -ojson | jq -r ".loadBalancingRules[] | select(.frontendPort == 6443) | .frontendIPConfiguration.id")
+----
+
+.. Set the `frontendipconfig_name` variable by running the following command:
++
+[source,terminal]
+----
+$ frontendipconfig_name=${frontendipconfig_id##*/}
+----
+
+.. To retrieve the IP address of the API service, run the following command:
++
+[source,terminal]
+----
+$ az network lb frontend-ip show -n ${frontendipconfig_name} --lb-name ${lb_name} -g ${cluster_resource_group_name} --query "privateIPAddress" -otsv
+----
+
+. If you are installing a public cluster, set the `lb_name` variable by running the following command:
++
+[source,terminal]
+----
+$ lb_name="${infra_id}"
+----
+
+
+.. Set the `frontendipconfig_id` variable by running the following command:
++
+[source,terminal]
+----
+$ frontendipconfig_id=$(az network lb show -n ${lb_name} -g ${cluster_resource_group_name} -ojson | jq -r ".loadBalancingRules[] | select(.frontendPort == 6443) | .frontendIPConfiguration.id")
+----
+
+.. Set the `frontendipconfig_name` variable by running the following command:
++
+[source,terminal]
+----
+$ frontendipconfig_name=${frontendipconfig_id##*/}
+----
+
+.. Set the `frontendpublicip_id` variable by running the following command:
++
+[source,terminal]
+----
+$ frontendpublicip_id=$(az network lb frontend-ip show -n ${frontendipconfig_name} --lb-name ${lb_name} -g ${cluster_resource_group_name} --query "publicIPAddress.id" -otsv)
+----
+
+.. To retrieve the IP address of the API service, run the following command:
++
+[source,terminal]
+----
+$ az network public-ip show --ids ${frontendpublicip_id} --query 'ipAddress' -otsv
+----
+
+. Use the IP address and your cluster name and base cluster domain to configure your own DNS record with the `api.<cluster_name>.<base_domain>.` hostname.
+
+. If you are installing a private cluster, set the `lb_name` variable by running the following command:
++
+[source,terminal]
+----
+$ lb_name="${infra_id}-internal"
+----
+
+.. Set the `frontendipconfig_id` variable by running the following command:
++
+[source,terminal]
+----
+$ frontendipconfig_id=$(az network lb show -n ${lb_name} -g ${cluster_resource_group_name} -ojson | jq -r ".loadBalancingRules[] | select(.frontendPort == 443) | .frontendIPConfiguration.id")
+----
+
+.. Set the `frontendipconfig_name` variable by running the following command:
++
+[source,terminal]
+----
+$ frontendipconfig_name=${frontendipconfig_id##*/}
+----
+
+.. To retrieve the IP address of the Ingress service, run the following command:
++
+[source,terminal]
+----
+$ az network lb frontend-ip show -n ${frontendipconfig_name} --lb-name ${lb_name} -g ${cluster_resource_group_name} --query "privateIPAddress" -otsv
+----
+
+. If you are installing a public cluster, set the `lb_name` variable by running the following command:
++
+[source,terminal]
+----
+$ lb_name="${infra_id}"
+----
+
+.. Set the `frontendipconfig_id` variable by running the following command:
++
+[source,terminal]
+----
+$ frontendipconfig_id=$(az network lb show -n ${lb_name} -g ${cluster_resource_group_name} -ojson | jq -r ".loadBalancingRules[] | select(.frontendPort == 443) | .frontendIPConfiguration.id")
+----
+
+.. Set the `frontendipconfig_name` variable by running the following command:
++
+[source,terminal]
+----
+$ frontendipconfig_name=${frontendipconfig_id##*/}
+----
+
+.. Set the `frontendpublicip_id` variable by running the following command:
++
+[source,terminal]
+----
+$ frontendpublicip_id=$(az network lb frontend-ip show -n ${frontendipconfig_name} --lb-name ${lb_name} -g ${cluster_resource_group_name} --query "publicIPAddress.id" -otsv)
+----
+
+.. To retrieve the IP address of the Ingress service, run the following command:
++
+[source,terminal]
+----
+$ az network public-ip show --ids ${frontendpublicip_id} --query 'ipAddress' -otsv
+----
+
+. Use the IP address and your cluster name and base cluster domain to configure your own DNS record with the `*.apps.<cluster_name>.<base_domain>.` hostname.