Add Azure KB articles

stories/assembly-azure-access.adoc

@@ -14,6 +14,11 @@ include::assembly-azure-hub-spoke-peering.adoc[leveloffset=+3]
 include::assembly-azure-vwan-peering.adoc[leveloffset=+3]
 include::assembly-azure-direct-peering.adoc[leveloffset=+3]
 
+// KB articles
+include::topics/proc-azure-user-defined-routing-tables.adoc[leveloffset=+2]
+include::topics/ref-azure-virtual-appliance-routing.adoc[leveloffset=+2]
+include::topics/proc-azure-private-dns.adoc[leveloffset=+2]
+
 // Accessing AAP
 include::topics/proc-azure-accessing-aap.adoc[leveloffset=+1]
 include::topics/proc-azure-license-association.adoc[leveloffset=+2]

stories/assembly-azure-install.adoc

@@ -34,6 +34,10 @@ include::topics/con-azure-aks-cidr.adoc[leveloffset=+3]
 // Prerequisites - Service Principal
 include::topics/proc-azure-create-service-principal.adoc[leveloffset=+2]
 
+// KB articles
+include::topics/ref-azure-policy.adoc[leveloffset=+2]
+include::topics/proc-azure-entitling-subscription.adoc[leveloffset=+2]
+
 // Deployment
 include::topics/proc-azure-deploy-aap.adoc[leveloffset=+1]
 

stories/assembly-azure-network-peering.adoc

@@ -1,13 +1,10 @@
 ifdef::context[:parent-context: {context}]
 
 [id="azure-network-peering"]
-= Private network peering
+= Private network peering for private deployments
 
 :context: azure-install
 
-// [role="_abstract"]
-// You can use these instructions to install
-
 {AAPonAzureNameShort} is deployed into an independent managed resource group with its own Azure virtual network (VNet).
 
 When initially deployed, {AAPonAzureNameShort}’s VNet can only send requests to external networks through the public internet.

stories/topics/proc-azure-entitling-subscription.adoc

@@ -0,0 +1,122 @@
+[id="azure-entitling-subscription_{context}"]
+
+// https://access.redhat.com/articles/6761811
+
+= Entitling your subscription
+
+== Obtaining a Subscription Entitlement
+
+There are a few different ways in which a support entitlement can be associated with your Red Hat account.
+Any of these methods will work.
+The method that you use may require future action, but these are provided to offer flexibility regarding how and when an entitlement is requested.
+
+=== The Ansible Automation Platform Deployment Driver
+
+When deploying Ansible Automation Platform on Microsoft Azure, the majority of the deployment is handled by an ephemeral component called "the deployment driver."
+It will only be available during the deployment of the solution; usually an hour or less.
+The URL to the deployment driver is provided about 15 minutes into the deployment as part of the "parameters and outputs" of the managed application within Azure Portal.
+
+When you open the deployment driver URL, you will receive a pop-up asking you to sign in the Red Hat Hybrid Cloud Console with your Red Hat account.
+When you click this link and login, you will be issued a support entitlement, or you will receive confirmation that you already have a support entitlement.
+In cases where you receive a new entitlement, you may also receive an email asking that you confirm the entitlement request.
+Be sure to acknowledge the email so that your entitlement is properly issued.
+
+In the event that you do not open the deployment driver before it completes and is removed from the platform, then you may use one of the following options.
+
+==== Red Hat Subscription Offering
+
+The Azure Marketplace has an offering entitled "Red Hat Subscription Support Registration."
+This is a free marketplace solution that will connect an Azure account to a Red Hat account for support purposes.
+Registering your Ansible Automation Platform support subscription with this model will automatically renew your support subscription as long as you have an active Ansible Automation Platform on Microsoft Azure deployment.
+Due to this automatic renewal, this method is recommended above the
+link:https://access.redhat.com/articles/6761811#manual-association[manual association] method.
+
+. Log in to the Azure console.
+. Navigate to the Azure Marketplace.
+. Search for "Red Hat Subscription Support Registration"
+** If your Azure subscription is billed outside of EMEA countries, then select the offer from Red Hat Inc.
+** If you Azure subscription is billed inside EMEA countries, then select the offer from Red Hat Limited.
+** You should be able to determine which offer to select by selecting the offer that has the text "Starts at 'free'" in the listing.
+. Click subscribe.
+. Choose a resource group for the subscription, or create a new one.
+. Name the subscription.
+. Ensure that 'Recurring billing' is true, even though priced free.
+. Click Review + subscribe.
+. Click subscribe.
+. Click Configure account now.
+** You will be redirected to Red Hat Hybrid Cloud Console.
+** If you are not already logged in, then you will need to login with a Red Hat account.
+. Check I have read and agree to the terms and conditions.
+. Click Connect accounts
++
+The process can take a few seconds.
+. You will be redirected to a page with a message indicating that the process succeeded or failed.
+Once this process is completed, it can can between 2 and 48 hours for an entitlement to be issued to your account.
+
+==== Manual Association
+
+The Ansible on Azure marketplace offers have a section called "Before You Begin". This section contains a link, which you will need to click and follow instructions.
+
+. Navigate to the Ansible Automation Platform on Microsoft Azure offering that you intend to deploy.
+. Under the "Before you begin" section, select the "Click here to enable your Red Hat product..." link in the offering description.
+** You will be redirected to Red Hat Hybrid Cloud Console.
+** If you are not already logged in, then you will need to login with a Red Hat account.
++
+image::azure-marketplace-offering.png[Red Hat Ansible Automation Platform on Azure marketplace offering]
+. You should receive a message on the screen that your entitlement request was received.
+. You will also receive an email to the email address associated with your Red Hat account within 8 business hours asking you to confirm/respond to your entitlement request.
+** If you omit this step or do not respond within 7 business days, you will not receive an account entitlement.
+** Check junk filters if you do not receive the email within a few hours.
+** The follow-up email after confirmation should contain a product code.
+. There are 2 ways to confirm your entitlement renewal:
+** Direct Hyperlink Activation:
+... Make sure you are logged into the Red Hat Customer Portal.
+... Within the confirmation email, click on the "ACTIVATE YOUR SUBSCRIPTION" hyperlink.
+** Manual Confirmation:
+*** Visit https://access.redhat.com/activate and copy paste the product code from your confirmation email.
+**** If you have an existing entitlement, select RENEW entitlement.
+**** If your previous entitlement has expired, select NEW entitlement.
+. Once confirmed, you will receive an entitlement issued to your account - usually within 8 business hours.
+
+If entitling via this process, then you will receive a notification by email to repeat the process each year.
+Failure to repeat will mean that your support entitlement is not reissued until you complete the process again.
+You may use the link:https://access.redhat.com/articles/6761811#red-hat-subscription-offering[Red Hat Subscription Offering] after entitling with the manual process in order to receive automated entitlements in the future.
+
+== Attaching the Entitlement to Ansible Automation Platform
+
+When you first open the URL for Ansible Automation Controller, you will be asked to provide a subscription entitlement.
+This entitlement should have been assigned to the Red Hat account of the user the followed the steps in Obtaining the Subscription Entitlement.
+
+=== Credentials-based Entitlement Association
+
+. Select username/password as the method to retrieve your subscription.
+. Fill out the username and password fields with the values of the Red Hat account used to request a Red Hat entitlement.
+. Click the Get subscription button.
+. Select the radio button next to the listing "Red Hat Ansible Automation Platform, Premium (On-Demand, Enablement)".
+** This entitlement may have a managed node count of 1. This is expected and can be ignored.
+** The expiration date should be approximately 1 year from when you requested the entitlement.
+. Click select.
+. Click next.
+. Click submit.
+Ansible Automation Platform should now be configured with a support entitlement for the lifespan of the entitlement that you just assigned.
+
+=== Manual Entitlement Association
+
+Instead of using your username and password, you may follow these steps to acquire an entitlement package that you may also use to entitle Ansible Automation Platform:
+
+. Login to access.redhat.com with your Red Hat account credentials.
+. Click Subscriptions in the top left menu.
+. Click Subscription Allocations.
+. Click New Subscription Allocation.
+. Give the allocation a name and select Satellite 6.10 as the type.
+. Click Create; it may take a moment for the allocation to create.
+. Click on the Subscriptions tab in the middle of the page and then click Add Subscriptions.
+. A list of your available subscriptions will appear; find the "MCT4249--Red Hat Ansible Automation Platform, Premium (On-Demand, Enablement)" listing and associate the entitlement allocation.
+. Click Submit at the bottom of the page.
+. Once the allocation is associated with the subscription click the Export Manifest button to download the zip file containing the manifest.
+. Save this zip file for when you are asked for your subscription entitlement once the app is deployed.
+. Open the URL to Ansible Automation Controller provided as part of your deployment of Ansible Automation Platform on Azure.
+. When asked for a subscription manifest, choose the zip file that was downloaded to your computer in the previous step.
+
+Ansible Automation Platform should now be configured with a support entitlement for the lifespan of the entitlement that you just assigned.
+

stories/topics/proc-azure-private-dns.adoc

@@ -0,0 +1,69 @@
+[id="azure-private-dns_{context}"]
+
+// https://access.redhat.com/articles/6983525
+
+= Private DNS
+
+{AAPonAzureName} uses Azure's managed DNS services when deployed.
+To use private DNS records that cannot be resolved publicly,
+you may either use Azure Private DNS Zones that are peered to the managed application VNET,
+or you may submit DNS zones (via a submit request to Red Hat) that should be forwarded to a customer-managed private DNS server.
+
+When using private DNS, Red Hat only supports using FQDNs from the customer-managed private DNS server for security reasons.
+
+== Azure Private DNS Zones
+
+Azure Private DNS Zones are the preferred way to connect custom DNS records to {AAPonAzureName}.
+Each private DNS zone that you attach to the {AAPonAzureNameShort} VNET will attempt to perform a lookup for that domain within the private DNS zone first.
+If the record is not found, then the search will traverse through Azure DNS services to attempt to find a matching record.
+
+Azure Private DNS Zones are configurable by the customer, and are a native Azure service,
+which means that you have control to add, edit, and remove zones without contacting Red Hat.
+
+A limitation of Private DNS Zones is only one instance of a given zone may be linked to a Virtual Network.
+Customers will run into a conflict when attempting to link zones matching the names of Private DNS Zones in the managed resource group.
+Microsoft recommends customers consolidate DNS records into a single zone to work around this limitation.
+Customers may replicate the records from the zones in the managed resource group into their own instance of the Private DNS Zone.
+The Private DNS Zones in the managed resource group may then be unlinked from the Virtual Network and replaced with the customer's instance.
+Failure to properly maintain the records in the Private DNS Zone may prevent the managed application from operating.
+
+The AKS private DNS zone cannot be customer managed and still allow Red Hat to update or upgrade the managed AKS that is a part of this offering.
+That means that customers should not unlink the <GUID>.privatelink.<region>.azmk8s.io private DNS zone to allow Red Hat to upgrade the customer AKS to the latest version during the maintenance windows.
+See the following link for more information on this limitation: https://learn.microsoft.com/en-us/troubleshoot/azure/azure-kubernetes/create-upgrade-delete/createorupdatevirtualnetworklinkfailed-error
+To work around this limitation, Red Hat allows you to manage A and CNAME records in the Private DNS zones in the managed resource group.
+Any records that you put in the Private DNS zones in the managed resource group are visible to the Red Hat SREs.
+If you decide to use the Private DNS zones in the managed resource group, you are responsible for updating them with the records you need.
+Customer supplied records are not backed up as a part of the disaster recovery process.
+Removing any Azure supplied records can cause network connectivity issues with Ansible Automation Platform on Microsoft Azure.
+
+== Private DNS Servers
+
+If your organization uses private DNS servers, then you may send a list of DNS zones and your DNS server IP address(es) to Red Hat for configuration with your Red Hat Ansible Automation Platform on Microsoft Azure deployment.
+Red Hat SREs will configure your deployment so that lookups for the provided zones are passed to your custom DNS servers.
+
+This option requires that your custom DNS server(s) are routable from Ansible Automation Platform on Azure's VNET.
+This may require Azure networking configuration, such as VNET or WAN peering, that is the responsibility of the customer.
+
+Only the DNS zones that you explicitly provide can be routed through your private DNS servers.
+It is not possible to route all traffic through private DNS servers.
+
+To request private DNS server configuration,
+link:https://https://access.redhat.com/support/cases/#/case/list[submit a support request]
+to Red Hat using the following information:
+
+* Set the product to Ansible Automation Platform
+* Set the version to Azure Cloud
+* In the description, include:
+
+** The list of DNS search domains that require your private DNS servers
+** The IP address(es) of your private DNS servers
+** The fully qualified domain name of a host that should resolve with your custom DNS server so that Red Hat SREs can validate successful configuration
+** For example:
++
+----
+Private DNS search domain: mycompany.com
+Private DNS IPs: 10.8.8.8 10.8.4.4
+Test host: app1.mycompany.com
+
+----
+

stories/topics/proc-azure-user-defined-routing-tables.adoc

@@ -0,0 +1,56 @@
+[id="azure-user-defined-routing-tables_{context}"]
+
+// https://access.redhat.com/articles/7005411
+
+= User defined routing tables
+
+{AAPonAzureName} does allow customers to create user defined routes from the VNET deployed with the managed application to internal network ranges, firewalls, virtual network appliances, etc.
+This article describes how to configure user defined routes.
+
+Most of {AAPonAzureNameShort}'s resources are deployed into a Managed Resource Group that customers do not have access to edit.
+See more about those resource groups here.
+However, a route table is deployed into the "node pool resource group" that is user editable.
+This route table is attached to the proper subnets within the deployment to configure user defined routes.
+
+== Adding Routes to the Route Table
+
+Follow these steps to add routes to the route table:
+
+. Open the Azure Portal in your web browser.
+. Navigate to resource groups.
+. Select the "node pool resource group". It will follow the naming convention: rg-<identifier>-nodepool-<region>.
+. Select the route table. It will follow the naming convention: aks-agentpool-<identifier>-routetable.
+. Select "Routes" in the left menu.
+. Click "Add" to add a new route to your internal network.
+** Note that the "Next hop type" will depend on your internal networking configuration.
+If you have directly peered your networks, then "Virtual Network" is likely the selection that you need.
+If you have a firewall or other appliance that you need to route traffic through, then you will select "Virtual Network Appliance".
+** Each customer's cloud networking configuration is unique and requires planning configuration that is specific to Azure and not Ansible Automation Platform on Azure.
+Networking configuration changes may require network troubleshooting resources within a customer's domain, such as firewall rules, to ensure that traffic flows properly in order for Ansible Automation Platform to operate properly.
+. Add the routes to your external networks as a unique route per-network.
+** Note that you will need to perform a similar exercise from your other route tables to ensure that traffic can route from those networks to the Ansible on Azure network.
+
+[NOTE]
+====
+There are two or more routes that AKS uses in this route table. Do not edit or delete these routes as that change will break the networking configuration of your managed application deployment.
+====
+
+== Propagating Routes
+
+By default, the "Propagate gateway routes" configuration is enabled.
+If your organization uses an Azure Virtual Network Gateway or Virtual Network Appliance that propagates BGP routes,
+then this configuration will auto-configure routing between other networks and the Ansible on Azure route table.
+
+If your organization uses a networking deployment that does not, or should not, propagate routes automatically,
+then you will want to disable this setting to ensure that your user defined routing works as expected.
+
+Follow these steps to enable or disable route propagation:
+
+. Open the Azure Portal in your web browser.
+. Navigate to resource groups.
+. Select the "node pool resource group". It will follow the naming convention: rg-<identifier>-nodepool-<region>.
+. Select the route table. It will follow the naming convention: aks-agentpool-<identifier>-routetable.
+. Click "Configuration" in the left menu.
+. Select "Yes" or "No" to enable or disable route propagation based on your needs.
+. Click "Save".
+

stories/topics/ref-azure-policy.adoc

@@ -0,0 +1,25 @@
+:_content-type: REFERENCE
+
+// from https://access.redhat.com/articles/7013454
+
+[id="azure-policy_{context}"]
+= Azure Policy
+
+[role="_abstract"]
+Azure Policy is a tool to help organizations enforce compliance of Azure resources to defined standards.
+Use cases for Azure Policy are the enforcement of naming schemes, deployment regions, and the consistent application of tags.
+
+The application of Azure Policy can interfere with both operation and maintenance of Ansible on Azure.
+Red Hat recommends organizations exclude the enforcement of any Azure Policy on resources associated with the managed application.
+
+The resource groups for Ansible on Azure follow a default naming scheme:
+
+[options="header"]
+|===
+|Pattern |Example
+|mrg-rhaapomsa-[0-9]+
+|mrg-rhaapomsa-20230417040411
+|rg-aap[a-z06]+-nodepools-[deployment_region]
+|rg-aapl1am6d8v1dhr9y-nodepools-centralus
+|===
+