Restructure documentation for Azure VNET (#42215)

Co-authored-by: github-actions <[email protected]> Co-authored-by: Matt Pollard <[email protected]> Co-authored-by: Grace Park <[email protected]>
mkfarmsllcinfo · Sep 19, 2023 · 6d7c31d · 6d7c31d
1 parent 1fadc01
commit 6d7c31d
Show file tree

Hide file tree

Showing 24 changed files with 552 additions and 424 deletions.
diff --git a/assets/images/help/actions/actions-vnet-injected-larger-runners-architecture.png b/assets/images/help/actions/actions-vnet-injected-larger-runners-architecture.png
diff --git a/...ed-runners/about-github-hosted-runners.md → ...ed-runners/about-github-hosted-runners.md b/...ed-runners/about-github-hosted-runners.md → ...ed-runners/about-github-hosted-runners.md
diff --git a/...ners/customizing-github-hosted-runners.md → ...ners/customizing-github-hosted-runners.md b/...ners/customizing-github-hosted-runners.md → ...ners/customizing-github-hosted-runners.md
@@ -8,6 +8,8 @@ type: tutorial
 topics:
   - Workflows
 shortTitle: Customize runners
+redirect_from:
+  - /actions/using-github-hosted-runners/customizing-github-hosted-runners
 ---
 
 {% data reusables.actions.enterprise-github-hosted-runners %}

diff --git a/content/actions/using-github-hosted-runners/about-github-hosted-runners/index.md b/content/actions/using-github-hosted-runners/about-github-hosted-runners/index.md
@@ -0,0 +1,15 @@
+---
+title: Using GitHub-hosted runners
+shortTitle: About GitHub-hosted runners
+intro: '{% data variables.product.prodname_dotcom %} offers hosted virtual machines to run workflows. The virtual machine contains an environment of tools, packages, and settings available for {% data variables.product.prodname_actions %} to use.'
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '*'
+children:
+  - /about-github-hosted-runners
+  - /monitoring-your-current-jobs
+  - /customizing-github-hosted-runners
+---
+
+{% data reusables.actions.enterprise-github-hosted-runners %}
diff --git a/...d-runners/monitoring-your-current-jobs.md → ...d-runners/monitoring-your-current-jobs.md b/...d-runners/monitoring-your-current-jobs.md → ...d-runners/monitoring-your-current-jobs.md
@@ -4,6 +4,8 @@ shortTitle: Monitor current jobs
 intro: 'Monitor how {% data variables.product.prodname_dotcom %}-hosted runners are processing jobs in your organization or enterprise, and identify any related constraints.'
 versions:
   feature: github-runner-dashboard
+redirect_from:
+  - /actions/using-github-hosted-runners/monitoring-your-current-jobs
 ---
 
 {% data reusables.actions.enterprise-github-hosted-runners %}

diff --git a/...ub-hosted-runners/about-larger-runners.md → ...ut-larger-runners/about-larger-runners.md b/...ub-hosted-runners/about-larger-runners.md → ...ut-larger-runners/about-larger-runners.md
diff --git a/...s/controlling-access-to-larger-runners.md → ...s/controlling-access-to-larger-runners.md b/...s/controlling-access-to-larger-runners.md → ...s/controlling-access-to-larger-runners.md
@@ -6,6 +6,8 @@ permissions: '{% data reusables.actions.larger-runner-permissions %}'
 versions:
   feature: actions-hosted-runners
 type: tutorial
+redirect_from:
+  - /actions/using-github-hosted-runners/controlling-access-to-larger-runners
 ---
 
 {% data reusables.actions.enterprise-github-hosted-runners %}

diff --git a/content/actions/using-github-hosted-runners/about-larger-runners/index.md b/content/actions/using-github-hosted-runners/about-larger-runners/index.md
@@ -0,0 +1,14 @@
+---
+title: About larger runners
+shortTitle: About larger runners
+intro: '{% data variables.product.prodname_dotcom %} offers runners with more RAM, CPU, and disk space.'
+versions:
+  feature: actions-hosted-runners
+children:
+  - /about-larger-runners
+  - /managing-larger-runners
+  - /controlling-access-to-larger-runners
+  - /running-jobs-on-larger-runners
+---
+
+{% data reusables.actions.enterprise-github-hosted-runners %}
diff --git a/...hosted-runners/managing-larger-runners.md → ...larger-runners/managing-larger-runners.md b/...hosted-runners/managing-larger-runners.md → ...larger-runners/managing-larger-runners.md
@@ -5,6 +5,8 @@ intro: 'You can configure {% data variables.actions.hosted_runner %}s for your o
 permissions: '{% data reusables.actions.larger-runner-permissions %}'
 versions:
   feature: actions-hosted-runners
+redirect_from:
+  - /actions/using-github-hosted-runners/managing-larger-runners
 ---
 
 {% ifversion ghec %}

diff --git a/...runners/running-jobs-on-larger-runners.md → ...runners/running-jobs-on-larger-runners.md b/...runners/running-jobs-on-larger-runners.md → ...runners/running-jobs-on-larger-runners.md
@@ -5,6 +5,8 @@ intro: 'You can speed up your workflows by configuring them to run on {% data va
 permissions: '{% data reusables.actions.larger-runner-permissions %}'
 versions:
   feature: actions-hosted-runners
+redirect_from:
+  - /actions/using-github-hosted-runners/running-jobs-on-larger-runners
 ---
 
 ## Running jobs on your runner

diff --git a/content/actions/using-github-hosted-runners/connecting-to-a-private-network.md b/content/actions/using-github-hosted-runners/connecting-to-a-private-network.md
diff --git a/...ing-to-a-private-network/about-private-networking-with-github-hosted-runners.md b/...ing-to-a-private-network/about-private-networking-with-github-hosted-runners.md
@@ -0,0 +1,46 @@
+---
+title: About private networking with GitHub-hosted runners
+shortTitle: About private networking
+intro: '{% data reusables.actions.private-networking-intro %}'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghec: '*'
+type: overview
+topics:
+  - Actions
+  - Developer
+---
+
+{% data reusables.actions.enterprise-github-hosted-runners %}
+
+## About {% data variables.product.prodname_dotcom %}-hosted runners networking
+
+By default, {% data variables.product.prodname_dotcom %}-hosted runners have access to the public internet. However, you may also want these runners to access resources on your private network, such as a package registry, a secret manager, or other on-premise services.
+
+{% data variables.product.prodname_dotcom %}-hosted runners are shared across all {% data variables.product.prodname_dotcom %} customers, so you will need a way of connecting your private network to just your runners while they are running your workflows. There are a few different approaches you could take to configure this access, each with different advantages and disadvantages.
+
+## Using an API Gateway with OIDC
+
+{% data reusables.actions.private-networking-oidc-intro %} For more information, see "[AUTOTITLE](/actions/using-github-hosted-runners/connecting-to-a-private-network/using-an-api-gateway-with-oidc)."
+
+## Using WireGuard to create a network overlay
+
+{% data reusables.actions.private-networking-wireguard-intro %} For more information, see "[AUTOTITLE](/actions/using-github-hosted-runners/connecting-to-a-private-network/using-wireguard-to-create-a-network-overlay)."
+
+{% ifversion actions-private-networking-azure-vnet %}
+
+## Using an Azure Virtual Network (VNET)
+
+{% note %}
+
+**Notes:**
+
+- {% data reusables.actions.github-hosted-larger-runners-azure-vnet-beta %}
+- Only larger runners are supported with Azure VNET. For more information about larger runners, see "[AUTOTITLE](/enterprise-cloud@latest/actions/using-github-hosted-runners/about-larger-runners)."
+
+{% endnote %}
+
+{% data reusables.actions.azure-vnet-injected-runners-intro %} For more information, see "[AUTOTITLE](/actions/using-github-hosted-runners/connecting-to-a-private-network/about-using-github-hosted-runners-in-your-azure-virtual-network)."
+
+{% endif %}
diff --git a/...vate-network/about-using-github-hosted-runners-in-your-azure-virtual-network.md b/...vate-network/about-using-github-hosted-runners-in-your-azure-virtual-network.md
@@ -0,0 +1,58 @@
+---
+title: About using GitHub-hosted runners in your Azure Virtual Network
+shortTitle: About using a VNET
+intro: 'You can create {% data variables.product.company_short %}-hosted runners in your Azure Virtual Network(s) (VNET).'
+versions:
+  feature: actions-private-networking-azure-vnet
+type: overview
+topics:
+  - Actions
+  - Developer
+---
+
+## About using {% data variables.product.company_short %}-hosted runners in your Azure Virtual Network (VNET)
+
+{% note %}
+
+**Notes:**
+
+- {% data reusables.actions.github-hosted-larger-runners-azure-vnet-beta %}
+- Only larger runners are supported with Azure VNET. For more information about larger runners, see "[AUTOTITLE](/enterprise-cloud@latest/actions/using-github-hosted-runners/about-larger-runners)."
+
+{% endnote %}
+
+{% data reusables.actions.azure-vnet-injected-runners-intro %}
+
+Using {% data variables.product.company_short %}-hosted runners within Azure VNET allows you to perform the following actions.
+- Privately connect a runner to resources inside an Azure VNET without opening internet ports, including on-premises resources accessible from the Azure VNET.
+- Restrict what {% data variables.product.company_short %}-hosted runners can access or connect to with full control over outbound network policies.
+- Monitor network logs for {% data variables.product.company_short %}-hosted runners and view all connectivity to and from a runner.
+
+## About network communication
+
+To facilitate communication between {% data variables.product.company_short %} networks and your VNET, {% data variables.product.company_short %}-hosted runner's network interface card (NIC) deploys into your Azure VNET. This way, all communication is kept private within the network boundaries, and networking policies applied to the VNET also apply to the runner.
+
+![Diagram of the network communication architecture between GitHub networks and your private networks. The diagram describes each step in connecting GitHub-hosted runners to an Azure VNET. Each step is numbered and the numbers correspond to the numbered descriptions of the step listed below the diagram.](/assets/images/help/actions/actions-vnet-injected-larger-runners-architecture.png)
+
+1. A {% data variables.product.prodname_actions %} workflow is triggered.
+1. The {% data variables.product.prodname_actions %} service creates a runner.
+1. The runner service deploys the {% data variables.product.company_short %}-hosted runner's network interface card (NIC) into your Azure VNET.
+1. The runner agent picks up the workflow job. The {% data variables.product.prodname_actions %} service queues the job.
+1. The runner sends logs back to the {% data variables.product.prodname_actions %} service.
+1. The NIC accesses on-premise resources.
+
+## Using your VNET's network policies
+
+Because the {% data variables.product.company_short %}-hosted runner's NIC is deployed into your Azure VNET, networking policies applied to the VNET also apply to the runner.
+
+For example, if your VNET is configured with an Azure ExpressRoute to provide access to on-premises resources (artifactory) or connected to a VPN tunnel to provide access to other cloud-based resources, those access policies also apply to your runners. Additionally, any outbound rules applied to your VNET's network security group (NSG) also apply, giving you the ability to control outbound access for your runners
+
+If you have enabled any network logs monitoring for your VNET, you can also monitor network traffic for your runners.
+
+## Using {% data variables.product.company_short %}-hosted runners with an Azure VNET
+
+To use {% data variables.product.company_short %}-hosted runners with Azure VNET, you must configure Azure and configure your {% data variables.product.company_short %} settings to use {% data variables.product.company_short %}-hosted runners with a VNET.
+
+For more information about configuring Azure, see "[AUTOTITLE](/actions/using-github-hosted-runners/connecting-to-a-private-network/configuring-an-azure-virtual-network-for-your-enterprise)."
+
+For more information about configuring your {% data variables.product.company_short %} settings to use {% data variables.product.company_short %}-hosted runners with a VNET, see "[AUTOTITLE](/actions/using-github-hosted-runners/connecting-to-a-private-network/configuring-your-github-settings-for-use-with-azure-virtual-network)."
diff --git a/...onfiguring-azure-resources-for-private-networking-with-github-hosted-runners.md b/...onfiguring-azure-resources-for-private-networking-with-github-hosted-runners.md
@@ -0,0 +1,213 @@
+---
+title: Configuring Azure resources for private networking with GitHub-hosted runners
+shortTitle: Configuring Azure resources
+intro: 'Learn how to configure your Azure Virtual Network (VNET) to use {% data variables.product.company_short %}-hosted runners.'
+versions:
+  feature: actions-private-networking-azure-vnet
+type: how_to
+topics:
+  - Actions
+  - Developer
+redirect_from:
+  - /actions/using-github-hosted-runners/connecting-to-a-private-network/configuring-an-azure-virtual-network-for-your-enterprise
+---
+
+{% note %}
+
+**Note:** {% data reusables.actions.github-hosted-larger-runners-azure-vnet-beta %}
+
+{% endnote %}
+
+## About configuring your Azure resources
+
+To use an Azure VNET for private networking, you must configure your Azure resources. You can use the following script to automate the process. For more information about private networking, see "[AUTOTITLE](/actions/using-github-hosted-runners/connecting-to-a-private-network/about-private-networking-with-github-hosted-runners)."
+
+## Prerequisites
+
+To configure {% data variables.product.prodname_actions %} for VNET-injection, you must use an Azure account with the Subscription Contributor role and the Network Contributor role. These roles enable you to register the resource provider and delegate the subnet. For more information, see [Azure built-in roles](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles) in the Azure documentation.
+
+To correctly associate the subnets with the right user, Azure `NetworkSettings` resources must be created in the same subscriptions where virtual networks are created.
+
+To ensure resource availability/data residency, resources must be created in the same Azure region.
+
+After you configure your Azure subscription, share your Azure Subscription ID with your {% data variables.product.company_short %} contact to enroll in the beta.
+
+Save the following `.bicep` file in the same directory location of the script. Name the file `actions-nsg-deployment.bicep`.
+
+```yaml copy
+@description('NSG for outbound rules')
+param location string
+param nsgName string = 'actions_NSG'
+
+resource actions_NSG 'Microsoft.Network/networkSecurityGroups@2017-06-01' = {
+  name: nsgName
+  location: location
+  properties: {
+    securityRules: [
+      {
+        name: 'DenyInternetOutBoundOverwrite'
+        properties: {
+          protocol: '*'
+          sourcePortRange: '*'
+          destinationPortRange: '*'
+          sourceAddressPrefix: '*'
+          destinationAddressPrefix: 'Internet'
+          access: 'Deny'
+          priority: 400
+          direction: 'Outbound'
+        }
+      }
+      {
+        name: 'AllowVnetOutBoundOverwrite'
+        properties: {
+          protocol: 'TCP'
+          sourcePortRange: '*'
+          destinationPortRange: '443'
+          sourceAddressPrefix: '*'
+          destinationAddressPrefix: 'VirtualNetwork'
+          access: 'Allow'
+          priority: 200
+          direction: 'Outbound'
+          destinationAddressPrefixes: []
+        }
+      }
+      {
+        name: 'AllowAzureCloudOutBound'
+        properties: {
+          protocol: 'TCP'
+          sourcePortRange: '*'
+          destinationPortRange: '443'
+          sourceAddressPrefix: '*'
+          destinationAddressPrefix: 'AzureCloud'
+          access: 'Allow'
+          priority: 210
+          direction: 'Outbound'
+          destinationAddressPrefixes: []
+        }
+      }
+      {
+        name: 'AllowInternetOutBoundGitHub'
+        properties: {
+          protocol: 'TCP'
+          sourcePortRange: '*'
+          destinationPortRange: '443'
+          sourceAddressPrefix: '*'
+          access: 'Allow'
+          priority: 220
+          direction: 'Outbound'
+          destinationAddressPrefixes: [
+            '140.82.112.0/20'
+            '142.250.0.0/15'
+            '143.55.64.0/20'
+            '192.30.252.0/22'
+            '185.199.108.0/22'
+          ]
+        }
+      }
+      {
+        name: 'AllowInternetOutBoundMicrosoft'
+        properties: {
+          protocol: 'TCP'
+          sourcePortRange: '*'
+          destinationPortRange: '443'
+          sourceAddressPrefix: '*'
+          access: 'Allow'
+          priority: 230
+          direction: 'Outbound'
+          destinationAddressPrefixes: [
+            '13.64.0.0/11'
+            '13.96.0.0/13'
+            '13.104.0.0/14'
+            '20.33.0.0/16'
+            '20.34.0.0/15'
+            '20.36.0.0/14'
+            '20.40.0.0/13'
+            '20.48.0.0/12'
+            '20.64.0.0/10'
+            '20.128.0.0/16'
+            '52.224.0.0/11'
+            '204.79.197.200'
+          ]
+        }
+      }
+    {
+        name: 'AllowInternetOutBoundCannonical'
+        properties: {
+          protocol: 'TCP'
+          sourcePortRange: '*'
+          destinationPortRange: '443'
+          sourceAddressPrefix: '*'
+          destinationAddressPrefix: '185.125.188.0/22'
+          access: 'Allow'
+          priority: 240
+          direction: 'Outbound'
+          destinationAddressPrefixes: []
+        }
+      }
+    ]
+  }
+}
+```
+
+## Using a script to configure your Azure resources
+
+Use the following script to set up a subnet with VNET-injection in Azure. The script creates all resources in the same resource group.
+
+To use the script, fill in the placeholder environment variable values with the actual values and run the script from a bash shell or Windows Subsystem for Linux.
+
+```bash copy
+#!/bin/bash
+
+# This script creates the following resources in the specified subscription:
+# - Resource group
+# - Network Security Group rules
+# - Virtual network (vnet) and subnet
+# - Network Settings with specified subnet and GitHub Enterprise databse ID
+#
+# It also registers the `GitHub.Network` resource provider with the subscription,
+# delegates the created subnet to the Actions service via the `GitHub.Network/NetworkSettings`
+# resource type, and applies the NSG rules to the created subnet.
+
+# stop on failure
+set -e
+
+#set environment
+AZURE_LOCATION=YOUR_AZURE_LOCATION
+SUBSCRIPTION_ID=YOUR_SUBSCRIPTION_ID
+RESOURCE_GROUP_NAME=YOUR_RESOURCE_GROUP_NAME
+VNET_NAME=YOUR_VNET_NAME
+SUBNET_NAME=YOUR_SUBNET_NAME
+NSG_NAME=YOUR_NSG_NAME
+NETWORK_SETTINGS_RESOURCE_NAME=YOUR_NETWORK_SETTINGS_RESOURCE_NAME
+DATABASE_ID=YOUR_DATABASE_ID
+
+echo login to Azure
+. az login --output none
+
+echo set account context $SUBSCRIPTION_ID
+. az account set --subscription $SUBSCRIPTION_ID
+
+echo Register resource provider GitHub.Network
+. az provider register --namespace GitHub.Network
+
+echo Create resource group $RESOURCE_GROUP_NAME at $AZURE_LOCATION
+. az group create --name $RESOURCE_GROUP_NAME --location $AZURE_LOCATION
+
+echo Create NSG rules deployed with 'actions-nsg-deployment.bicep' file
+. az deployment group create --resource-group $RESOURCE_GROUP_NAME --template-file ./actions-nsg-deployment.bicep --parameters location=$AZURE_LOCATION nsgName=$NSG_NAME
+
+echo Create vnet $VNET_NAME and subnet $SUBNET_NAME
+. az network vnet create --resource-group $RESOURCE_GROUP_NAME --name $VNET_NAME --address-prefix 10.0.0.0/16 --subnet-name $SUBNET_NAME --subnet-prefixes 10.0.0.0/24
+
+echo Delegate subnet to GitHub.Network/networkSettings and apply NSG rules
+. az network vnet subnet update --resource-group $RESOURCE_GROUP_NAME --name $SUBNET_NAME --vnet-name $VNET_NAME --delegations GitHub.Network/networkSettings --network-security-group $NSG_NAME
+
+echo Create network settings resource $NETWORK_SETTINGS_RESOURCE_NAME
+. az resource create --resource-group $RESOURCE_GROUP_NAME  --name $NETWORK_SETTINGS_RESOURCE_NAME --resource-type GitHub.Network/networkSettings --properties "{ \"location\": \"$AZURE_LOCATION\", \"properties\" : {  \"subnetId\": \"/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP_NAME/providers/Microsoft.Network/virtualNetworks/$VNET_NAME/subnets/$SUBNET_NAME\", \"organizationId\": \"$DATABASE_ID\" }}" --is-full-object --api-version 2023-03-15-beta
+
+echo To clean up and delete resources run the following command:
+echo az group delete --resource-group $RESOURCE_GROUP_NAME
+
+```
+
+The script will return the full payload for the created resource. The `GitHubId` hash value returned in the payload for the created resource is the network settings resource ID you will use in the next steps while configuring VNET settings with {% data variables.product.company_short %}.