From 2f5af8999ddcc155319820c4eb671a35d9153145 Mon Sep 17 00:00:00 2001 From: Wael Kdouh Date: Wed, 3 Jan 2024 15:55:03 -0500 Subject: [PATCH] Docs refactoring --- SECURITY.md | 2 +- docs/SECURITY.md | 2 +- .../0-labPrerequisites/apim-basic-concepts-0-2.md | 2 +- docs/apiops/1-supportedScenarios/index.md | 2 +- docs/apiops/2-apimCreation/index.md | 2 +- docs/apiops/3-apimTools/apimtools-azdo-2-3-new.md | 8 ++++---- docs/apiops/3-apimTools/apimtools-azdo-2-3-old.md | 10 +++++----- docs/apiops/3-apimTools/apimtools-github-2-4-new.md | 2 +- docs/apiops/3-apimTools/apimtools-github-2-4-old.md | 2 +- docs/apiops/3-apimTools/apiops-2-1-tools-extractor.md | 4 ++-- docs/apiops/3-apimTools/apiops-2-2-tools-publisher.md | 4 ++-- .../apiops-7-3-supportedresources.md | 2 +- docs/assets/diagrams/apimADSv2.drawio | 2 +- docs/assets/diagrams/apimADSv2.svg | 2 +- 14 files changed, 23 insertions(+), 23 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index f7b89984..9badf679 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,7 +4,7 @@ Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). -If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below. +If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://learn.microsoft.com/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below. ## Reporting Security Issues diff --git a/docs/SECURITY.md b/docs/SECURITY.md index d4ac0df7..11cd7b96 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -8,7 +8,7 @@ nav_exclude: true Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). -If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below. +If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://learn.microsoft.com/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below. ## Reporting Security Issues diff --git a/docs/apiops/0-labPrerequisites/apim-basic-concepts-0-2.md b/docs/apiops/0-labPrerequisites/apim-basic-concepts-0-2.md index b5122006..a544746d 100644 --- a/docs/apiops/0-labPrerequisites/apim-basic-concepts-0-2.md +++ b/docs/apiops/0-labPrerequisites/apim-basic-concepts-0-2.md @@ -20,7 +20,7 @@ In this section we provide you with a template architecture diagram for your api - Please bear in mind that APIOPS is designed to facilitate the promotion of changes across different Azure API Management (APIM) instances. While the image below illustrates changes within the same instance, it's important to note that you can effortlessly apply your modifications across various Azure APIM instances using the supported configuration system. We advise taking some time to explore the [wiki](https://github.com/Azure/apiops/wiki/Configuration) and [documentation](https://azure.github.io/apiops/apiops/5-publishApimArtifacts/apiops-azdo-4-1-pipeline.html) to grasp the functioning of configuration overrides when promoting changes across different environments. -![](https://docs.microsoft.com/en-us/azure/architecture/example-scenario/devops/media/automated-api-deployments-architecture-diagram.png) +![](https://learn.microsoft.com/azure/architecture/example-scenario/devops/media/automated-api-deployments-architecture-diagram.png) Download Diagram: - [Visio](https://arch-center.azureedge.net/automated-api-deployments-apiops-architecture-diagram.vsdx) diff --git a/docs/apiops/1-supportedScenarios/index.md b/docs/apiops/1-supportedScenarios/index.md index 4085ed29..5ca699e1 100644 --- a/docs/apiops/1-supportedScenarios/index.md +++ b/docs/apiops/1-supportedScenarios/index.md @@ -32,7 +32,7 @@ Create all the different artifacts from an IDE (e.g. VS Code) -> commit the chan In this scenario you don't need to utilize the extractor tool to generate the artifacts as the artifacts will be created in the IDE. Having said that, nothing prevents you from utilizing the extractor tool to generate the initial artifacts if you are introducing the tool to an existing APIM instance. # Supported 2022-09-01 -Below there is a table with all [artifacts extracted and published by APIOps](https://docs.microsoft.com/en-us/rest/api/apimanagement/). +Below there is a table with all [artifacts extracted and published by APIOps](https://learn.microsoft.com/rest/api/apimanagement/). |Operation Group|Description|Implemented in APIOps?| |:----|:----|:----| diff --git a/docs/apiops/2-apimCreation/index.md b/docs/apiops/2-apimCreation/index.md index 3b5fe14e..15baf088 100644 --- a/docs/apiops/2-apimCreation/index.md +++ b/docs/apiops/2-apimCreation/index.md @@ -13,7 +13,7 @@ An instance can take some time to provision. Expect ~45-75 minutes. Therefore, p [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.ApiManagement) -Using either your own or [Azure's common naming convention](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-naming), fill in each required field and press *Review + Create*, followed by *Create* to provision the service. Once started, it is not necessary to remain on this page or in the Azure Portal. If you entered a valid email address, you will receive a provisioning completion email. +Using either your own or [Azure's common naming convention](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/azure-best-practices/resource-naming), fill in each required field and press *Review + Create*, followed by *Create* to provision the service. Once started, it is not necessary to remain on this page or in the Azure Portal. If you entered a valid email address, you will receive a provisioning completion email. Please note that the **service name must be unique**. We recommend to include your initials and numeric date. Also we recommend that you add -prod in the name of the production instance to easily identify it in your DevOps scripts and configuration files. For example in the image below the prod instance would be called apim-apiops-prod. diff --git a/docs/apiops/3-apimTools/apimtools-azdo-2-3-new.md b/docs/apiops/3-apimTools/apimtools-azdo-2-3-new.md index 3bf328c7..99b3eed0 100644 --- a/docs/apiops/3-apimTools/apimtools-azdo-2-3-new.md +++ b/docs/apiops/3-apimTools/apimtools-azdo-2-3-new.md @@ -28,17 +28,17 @@ The older setup [can be found here](https://azure.github.io/apiops/apiops/3-apim In order to update the pipelines in the future you will follow the same steps documented in step 2. -3. [Create a pipeline variable group](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/variable-groups?view=azure-devops&tabs=classic#create-a-variable-group) called **apim-automation**. In that group, add these variables: - - **SERVICE_CONNECTION_NAME** and for its value, enter the name of your [Azure service connection](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml). +3. [Create a pipeline variable group](https://learn.microsoft.com/azure/devops/pipelines/library/variable-groups?view=azure-devops&tabs=classic#create-a-variable-group) called **apim-automation**. In that group, add these variables: + - **SERVICE_CONNECTION_NAME** and for its value, enter the name of your [Azure service connection](https://learn.microsoft.com/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml). - **APIM_NAME** and for its value, enter the name of lower environment apim instance name. You can optionally enter the **APIM_NAME** the higher environment if you have that information ready or you can enter it at a later point. - **RESOURCE_GROUP_NAME** and for its value, enter the resource group name of your Azure APIM instance. In this example we have two apim instances representing both the dev and prod environments so make sure you have two resource group entries representing both as shown in the image below. - **apiops_release_version** and for its value, enter the release number you would like to utilize. For example if you would like to utilize version 3 then you would set the value to **"v3.0.0"**. Its always recommended to utilize the latest release when possible as it usually includes new features and bug fixes. ![pipeline variable group](../../assets/images/variable_groups_new.png) -4. Create a target [**environment**](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/environments?view=azure-devops) called prod as shown below. The environment will allow us to require a manual approval between stages in a yaml based release pipeline. Choose Prod as the name and for the resource type choose None. ![prod environment](../../assets/images/ado_prod_environment.png) +4. Create a target [**environment**](https://learn.microsoft.com/azure/devops/pipelines/process/environments?view=azure-devops) called prod as shown below. The environment will allow us to require a manual approval between stages in a yaml based release pipeline. Choose Prod as the name and for the resource type choose None. ![prod environment](../../assets/images/ado_prod_environment.png) 5. After creating the environment add one ore more approvers by heading to the ellipses menu and click on "Approvals and checks" ![prod environment approvals](../../assets/images/ado_prod_environment_approvals.png) 6. Here we are adding a single approver but in an enterprise setting its recommended that you add two or more approvers. ![prod environment approver](../../assets/images/ado_prod_environment_approver.png) 7. Quick note about running a pipeline. > By default Azure DevOps build pipeline agents don't have enough permissions to perform some actions that are required for our pipeline. - > 1. To contribute to a repo, create a branch or update a pr. You need to grant that permission as discussed [here](https://docs.microsoft.com/en-us/azure/devops/pipelines/policies/set-permissions?toc=%2Fazure%2Fdevops%2Forganizations%2Fsecurity%2Ftoc.json&bc=%2Fazure%2Fdevops%2Forganizations%2Fsecurity%2Fbreadcrumb%2Ftoc.json&view=azure-devops) + > 1. To contribute to a repo, create a branch or update a pr. You need to grant that permission as discussed [here](https://learn.microsoft.com/azure/devops/pipelines/policies/set-permissions?toc=%2Fazure%2Fdevops%2Forganizations%2Fsecurity%2Ftoc.json&bc=%2Fazure%2Fdevops%2Forganizations%2Fsecurity%2Fbreadcrumb%2Ftoc.json&view=azure-devops) > 2. To contribute to artifact feed. You need to grant that permissions (contributor) as discussed [here](https://learn.microsoft.com/en-us/azure/devops/artifacts/feeds/feed-permissions?view=azure-devops#configure-feed-settings) 8. Thats it. You are now ready to extract and publish your Azure APIM instance artifacts. Refer to the extract and publish APIM artifacts sections for more information. For a list of supported artifacts refer to [this section ](https://azure.github.io/apiops/apiops/7-additionalTopics/apiops-7-3-supportedresources.html). diff --git a/docs/apiops/3-apimTools/apimtools-azdo-2-3-old.md b/docs/apiops/3-apimTools/apimtools-azdo-2-3-old.md index 3656d1d8..1a380f77 100644 --- a/docs/apiops/3-apimTools/apimtools-azdo-2-3-old.md +++ b/docs/apiops/3-apimTools/apimtools-azdo-2-3-old.md @@ -21,22 +21,22 @@ The updated setup [can be found here](https://azure.github.io/apiops/apiops/3-ap - pipelines - ... - utils -4. [Create an Azure Artifacts feed](https://docs.microsoft.com/en-us/azure/devops/artifacts/concepts/feeds?view=azure-devops#create-a-feed). We will use the name **apim-tools** in this tutorial. +4. [Create an Azure Artifacts feed](https://learn.microsoft.com/azure/devops/artifacts/concepts/feeds?view=azure-devops#create-a-feed). We will use the name **apim-tools** in this tutorial. ![artifacts_feed](../../assets/images/artifacts_feed.png) -5. [Create a pipeline variable group](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/variable-groups?view=azure-devops&tabs=classic#create-a-variable-group) called **apim-automation**. In that group, add these variables: +5. [Create a pipeline variable group](https://learn.microsoft.com/azure/devops/pipelines/library/variable-groups?view=azure-devops&tabs=classic#create-a-variable-group) called **apim-automation**. In that group, add these variables: - **ARTIFACTS_FEED_NAME** and for its value, enter the name of the artifacts feed you just created. - - **SERVICE_CONNECTION_NAME** and for its value, enter the name of your [Azure service connection](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml). + - **SERVICE_CONNECTION_NAME** and for its value, enter the name of your [Azure service connection](https://learn.microsoft.com/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml). - **APIM_NAME** and for its value, enter the name of lower environment apim instance name. - **RESOURCE_GROUP_NAME** and for its value, enter the resource group name of your Azure APIM instance. In this guide we have two apim instances representing both the dev and prod environments so make sure you have two resource group entries representing both as shown in the image below. ![pipeline variable group](../../assets/images/variable_groups.png) -6. Create a target [**environment**](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/environments?view=azure-devops) called prod as shown below. The environment will allow us to require a manual approval between stages in a yaml based release pipeline. Choose Prod as the name and for the resource type choose None. ![prod environment](../../assets/images/ado_prod_environment.png) +6. Create a target [**environment**](https://learn.microsoft.com/azure/devops/pipelines/process/environments?view=azure-devops) called prod as shown below. The environment will allow us to require a manual approval between stages in a yaml based release pipeline. Choose Prod as the name and for the resource type choose None. ![prod environment](../../assets/images/ado_prod_environment.png) 7. After creating the environment add one ore more approvers by heading to the ellipses menu and click on "Approvals and checks" ![prod environment approvals](../../assets/images/ado_prod_environment_approvals.png) 8. Here we are adding a single approver but in an enterprise setting its recommended that you add two or more approvers. ![prod environment approver](../../assets/images/ado_prod_environment_approver.png) 9. Create a new pipeline based on **publish-extractor.yaml**. This pipeline will compile the extractor tool whenever it's updated and publish it as a package in Azure DevOps Artifacts. Note that this file is found under the source code zipped folder under the release package that you have downloaded. ![extractor pipeline](../../assets/images/extractor_pipeline.png) 10. Run the pipeline. >Note : By default Azure DevOps build pipeline agents don't have enough permissions to perform some actions that are required for our pipeline. - > 1. To contribute to a repo, create a branch or update a pr. You need to grant that permission as discussed [here](https://docs.microsoft.com/en-us/azure/devops/pipelines/policies/set-permissions?toc=%2Fazure%2Fdevops%2Forganizations%2Fsecurity%2Ftoc.json&bc=%2Fazure%2Fdevops%2Forganizations%2Fsecurity%2Fbreadcrumb%2Ftoc.json&view=azure-devops) + > 1. To contribute to a repo, create a branch or update a pr. You need to grant that permission as discussed [here](https://learn.microsoft.com/azure/devops/pipelines/policies/set-permissions?toc=%2Fazure%2Fdevops%2Forganizations%2Fsecurity%2Ftoc.json&bc=%2Fazure%2Fdevops%2Forganizations%2Fsecurity%2Fbreadcrumb%2Ftoc.json&view=azure-devops) > 2. To contribute to artifact feed. You need to grant that permissions (contributor) as discussed [here](https://learn.microsoft.com/en-us/azure/devops/artifacts/feeds/feed-permissions?view=azure-devops#configure-feed-settings) 11. Create a new pipeline based on **publish-publisher.yaml**. This pipeline will compile the publisher tool whenever it's updated and publish it as a package in Azure DevOps Artifacts. 12. Run the pipeline. \ No newline at end of file diff --git a/docs/apiops/3-apimTools/apimtools-github-2-4-new.md b/docs/apiops/3-apimTools/apimtools-github-2-4-new.md index a80dceee..f8ae145e 100644 --- a/docs/apiops/3-apimTools/apimtools-github-2-4-new.md +++ b/docs/apiops/3-apimTools/apimtools-github-2-4-new.md @@ -23,7 +23,7 @@ The older setup [can be found here](https://azure.github.io/apiops/apiops/3-apim ![Github_Release](../../assets/images/Github_Release_Github.png) In order to update the pipelines in the future you will follow the same steps documented in step 2. -3. Next we will need to [Create an Azure AD Service Principal](https://docs.microsoft.com/en-us/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create-for-rbac) and configure its access to Azure resources. We will provide the SP with the contributor role to the resource groups hosting your different APIM instances. Make sure that you have the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) installed. Issue the following command twice on your command prompt (once for each environment). Make sure you replace the subscription id and resource group with your own information. +3. Next we will need to [Create an Microsoft Entra ID service principal](https://learn.microsoft.com/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create-for-rbac) and configure its access to Azure resources. We will provide the SP with the contributor role to the resource groups hosting your different APIM instances. Make sure that you have the [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed. Issue the following command twice on your command prompt (once for each environment). Make sure you replace the subscription id and resource group with your own information. - az ad sp create-for-rbac -n \"apiopslab\" \--role Contributor \--scopes /subscriptions/{subscription-id}/resourceGroups/{dev-resource-group} \--sdk-auth - az ad sp create-for-rbac -n \"apiopslab\" \--role Contributor \--scopes /subscriptions/{subscription-id}/resourceGroups/{prod-resource-group} \--sdk-auth - The output of the above az cli commands will be a json object as the one shown below. In the next step we will extract the four properties highlighted within the red box and and store them as secrets within each of your github repository environments. Note that for this guide we will create two Github [environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment), but in an enterprise setting you will probably have more environments between dev and production (e.g. QA). ![sp command](../../assets/images/sp_command_output.png) diff --git a/docs/apiops/3-apimTools/apimtools-github-2-4-old.md b/docs/apiops/3-apimTools/apimtools-github-2-4-old.md index 1e2ed055..8fede0c9 100644 --- a/docs/apiops/3-apimTools/apimtools-github-2-4-old.md +++ b/docs/apiops/3-apimTools/apimtools-github-2-4-old.md @@ -21,7 +21,7 @@ The updated setup [can be found here](https://azure.github.io/apiops/apiops/3-ap - ... - tools - code -4. Next we will need to [Create an Azure AD Service Principal](https://docs.microsoft.com/en-us/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create-for-rbac) and configure its access to Azure resources. We will provide the SP with the contributor role to the resource groups hosting your different APIM instances. Make sure that you have the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) installed. Issue the following command twice on your command prompt (once for each environment). Make sure you replace the subscription id and resource group with your own information. +4. Next we will need to [Create an Microsoft Entra ID service principal](https://learn.microsoft.com/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create-for-rbac) and configure its access to Azure resources. We will provide the SP with the contributor role to the resource groups hosting your different APIM instances. Make sure that you have the [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed. Issue the following command twice on your command prompt (once for each environment). Make sure you replace the subscription id and resource group with your own information. - az ad sp create-for-rbac -n \"apiopslab\" \--role Contributor \--scopes /subscriptions/{subscription-id}/resourceGroups/{dev-resource-group} \--sdk-auth - az ad sp create-for-rbac -n \"apiopslab\" \--role Contributor \--scopes /subscriptions/{subscription-id}/resourceGroups/{prod-resource-group} \--sdk-auth - The output of the above az cli commands will be a json object as the one shown below. In the next step we will extract the four properties highlighted within the red box and and store them as secrets within each of your github repository environments. Note that for this guide we will create two Github [environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment), but in an enterprise setting you will probably have more environments between dev and production (e.g. QA). ![sp command](../../assets/images/sp_command_output.png) diff --git a/docs/apiops/3-apimTools/apiops-2-1-tools-extractor.md b/docs/apiops/3-apimTools/apiops-2-1-tools-extractor.md index e95b610f..f543fe51 100644 --- a/docs/apiops/3-apimTools/apiops-2-1-tools-extractor.md +++ b/docs/apiops/3-apimTools/apiops-2-1-tools-extractor.md @@ -11,13 +11,13 @@ This section describes the extractor component which forms the core tool used to The extractor generates APIOps artifacts from an existing APIM instance. These artifacts can then be used as the source of truth for your APIM environment; make changes to them and have a CI/CD process update your Azure environment (with the publisher tool, for instance). ### Parameters -The tool expects certain configuration parameters. These can be passed as environment variables, command line arguments, etc. It will look for variables using the [``Host.CreateDefaultBuilder(arguments)``](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.hosting.host.createdefaultbuilder?view=dotnet-plat-ext-6.0#Microsoft_Extensions_Hosting_Host_CreateDefaultBuilder_System_String___) settings. Here are the expected parameters: +The tool expects certain configuration parameters. These can be passed as environment variables, command line arguments, etc. It will look for variables using the [``Host.CreateDefaultBuilder(arguments)``](https://learn.microsoft.com/dotnet/api/microsoft.extensions.hosting.host.createdefaultbuilder?view=dotnet-plat-ext-6.0#Microsoft_Extensions_Hosting_Host_CreateDefaultBuilder_System_String___) settings. Here are the expected parameters: | Variable | Purpose | | - | - | | AZURE_SUBSCRIPTION_ID | Subscription ID of the APIM instance to be extracted | | AZURE_RESOURCE_GROUP_NAME | Resource group name of the APIM instance to be extracted | -| AZURE_BEARER_TOKEN | Token for authentication to Azure. If this is not specified, the tool authenticate with the [``DefaultAzureCredential``](https://docs.microsoft.com/en-us/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet). | +| AZURE_BEARER_TOKEN | Token for authentication to Azure. If this is not specified, the tool authenticate with the [``DefaultAzureCredential``](https://learn.microsoft.com/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet). | | API_MANAGEMENT_SERVICE_NAME | Name of the APIM instance to be extracted | | API_MANAGEMENT_SERVICE_OUTPUT_FOLDER_PATH | Folder where the APIM artifacts will be saved | | API_SPECIFICATION_FORMAT | OpenAPI specification format. Valid options are **JSON** or **YAML**. If the variable is missing or invalid, **YAML** will be used by default | diff --git a/docs/apiops/3-apimTools/apiops-2-2-tools-publisher.md b/docs/apiops/3-apimTools/apiops-2-2-tools-publisher.md index a4423a0b..c98f2a30 100644 --- a/docs/apiops/3-apimTools/apiops-2-2-tools-publisher.md +++ b/docs/apiops/3-apimTools/apiops-2-2-tools-publisher.md @@ -10,14 +10,14 @@ This section describes the Publisher component which forms the core tool used to ## Publisher The Publisher tool updates the Azure APIM instance with the artifact folder contents. If a commit ID is specified in the parameters, it will update the instance with only files that were changed by the commit. In addition, the publisher tool picks up changes in the configuration yaml file when running the publisher. The configuration file is the only file outside of the artifacts folder that gets picked up by the publisher tool when promoting changes across environments. ### Parameters -The tool expects certain configuration parameters. These can be passed as environment variables, command line arguments, etc. It will look for variables using the [``Host.CreateDefaultBuilder(arguments)``](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.hosting.host.createdefaultbuilder?view=dotnet-plat-ext-6.0#Microsoft_Extensions_Hosting_Host_CreateDefaultBuilder_System_String___) settings. Here are the expected parameters: +The tool expects certain configuration parameters. These can be passed as environment variables, command line arguments, etc. It will look for variables using the [``Host.CreateDefaultBuilder(arguments)``](https://learn.microsoft.com/dotnet/api/microsoft.extensions.hosting.host.createdefaultbuilder?view=dotnet-plat-ext-6.0#Microsoft_Extensions_Hosting_Host_CreateDefaultBuilder_System_String___) settings. Here are the expected parameters: | Variable | Purpose | | - | - | | AZURE_SUBSCRIPTION_ID | Subscription ID of the APIM instance to be updated | | AZURE_RESOURCE_GROUP_NAME | Resource group name of the APIM instance to be updated | | API_MANAGEMENT_SERVICE_OUTPUT_FOLDER_PATH | Folder where the APIM artifacts are located | -| AZURE_BEARER_TOKEN | Token for authentication to Azure. If this is not specified, the tool authenticate with the [``DefaultAzureCredential``](https://docs.microsoft.com/en-us/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet) | +| AZURE_BEARER_TOKEN | Token for authentication to Azure. If this is not specified, the tool authenticate with the [``DefaultAzureCredential``](https://learn.microsoft.com/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet) | | API_MANAGEMENT_SERVICE_NAME | Name of the APIM instance to publish to. This can also be parsed from the configuration file | | ARM_API_VERSION | Azure ARM API version that will be used. This is a optional parameter and will default to **2022-04-01-preview** if not specified. Other versions can be found here [APIM Rest API Reference - Overview Docs](https://learn.microsoft.com/en-us/rest/api/apimanagement/current-ga/api-diagnostic/create-or-update?tabs=HTTP). | CONFIGURATION_YAML_PATH | Path to the Yaml configuration file used to override different configurations (e.g. policy backend value, namevalue pairs, just to name a few) when promoting across APIM environments (e.g. dev -> qa -> prod). You will need a unique Yaml configuration file per environment (e.g. configuration.prod.yaml for production) when overriding configurations across environments. The configuration file is not mandatory. If you don't provide it, the overrides will be picked from the environment variables as discussed in the wiki [here](https://github.com/Azure/apiops/wiki/Configuration#configuration-providers). Remember that you always need to provide the apimServiceName at a minimum which informs the publisher about the destination apim instance | diff --git a/docs/apiops/7-additionalTopics/apiops-7-3-supportedresources.md b/docs/apiops/7-additionalTopics/apiops-7-3-supportedresources.md index fdf46d99..e8fc8cdf 100644 --- a/docs/apiops/7-additionalTopics/apiops-7-3-supportedresources.md +++ b/docs/apiops/7-additionalTopics/apiops-7-3-supportedresources.md @@ -6,7 +6,7 @@ nav_order: 0 --- # Supported 2022-06-01 -Below there is a table with all [artifacts extracted and published by APIOps](https://docs.microsoft.com/en-us/rest/api/apimanagement/). Every artifact is marked as *supported* ✓, *not supported* ✗ or *skipped* **-**. +Below there is a table with all [artifacts extracted and published by APIOps](https://learn.microsoft.com/rest/api/apimanagement/). Every artifact is marked as *supported* ✓, *not supported* ✗ or *skipped* **-**. | Resource | Extracted | APIOps version | Developer comment | |---|---|---|---| diff --git a/docs/assets/diagrams/apimADSv2.drawio b/docs/assets/diagrams/apimADSv2.drawio index 8977a557..a9c78c99 100644 --- a/docs/assets/diagrams/apimADSv2.drawio +++ b/docs/assets/diagrams/apimADSv2.drawio @@ -114,7 +114,7 @@ - + diff --git a/docs/assets/diagrams/apimADSv2.svg b/docs/assets/diagrams/apimADSv2.svg index aa6d59f0..5bc73d40 100644 --- a/docs/assets/diagrams/apimADSv2.svg +++ b/docs/assets/diagrams/apimADSv2.svg @@ -1,4 +1,4 @@ -


















...
Subnet



































Subnet...
IP filter
Certificate - MTLS
Basic http key
IP filter...
Express Route
Express Route


















...
APIM ADS Questions

- What type of apis are you onboarding?   
- What deployment model works for you?  
- What tier of apim is the right for you?  
- What security will you add to your apis? 
- What products are we going to define? 
- What teams and processess need to be in place to manage the APIM?
APIM ADS Questions...
Azure APIs
Azure APIs


















...
On- Prem
On- PremDns Server
Azure APIM -  Internal Vnet
Azure APIM -  Internal VnetData ServicesData Services
           SSO
           SSO
Oauth2
Oauth2


















...
Consumers
ConsumersOn prem ApisInternal developersThird party appsAzure ADtenant
AKS
AKSApplicationGatewayWAF
PAAS services





PAAS services...
Keyvault
Keyvault
Application Insights
Applicati...
Event Hub
Event Hub
Azure Portal
SDKs
CLIs
Scripts
Terraform
Bicep
ARM
Azure Portal...
Publishers

















Publishers...Internal publishers
Azure Functions
Azure Funct...
App Services
App Servic...
VMs
VMs
Spring Cloud
Spring Cloud
Container Instances
Container...
Logic Apps
Logic Apps
Third Party APIs










Third Party APIs...Other APIsOther APIsOther APIsViewer does not support full SVG 1.1 \ No newline at end of file +


















...
Subnet



































Subnet...
IP filter
Certificate - MTLS
Basic http key
IP filter...
Express Route
Express Route


















...
APIM ADS Questions

- What type of apis are you onboarding?   
- What deployment model works for you?  
- What tier of apim is the right for you?  
- What security will you add to your apis? 
- What products are we going to define? 
- What teams and processess need to be in place to manage the APIM?
APIM ADS Questions...
Azure APIs
Azure APIs


















...
On- Prem
On- PremDns Server
Azure APIM -  Internal Vnet
Azure APIM -  Internal VnetData ServicesData Services
           SSO
           SSO
Oauth2
Oauth2


















...
Consumers
ConsumersOn prem ApisInternal developersThird party appsMicrosoft Entra IDtenant
AKS
AKSApplicationGatewayWAF
PAAS services





PAAS services...
Keyvault
Keyvault
Application Insights
Applicati...
Event Hub
Event Hub
Azure Portal
SDKs
CLIs
Scripts
Terraform
Bicep
ARM
Azure Portal...
Publishers

















Publishers...Internal publishers
Azure Functions
Azure Funct...
App Services
App Servic...
VMs
VMs
Spring Cloud
Spring Cloud
Container Instances
Container...
Logic Apps
Logic Apps
Third Party APIs










Third Party APIs...Other APIsOther APIsOther APIsViewer does not support full SVG 1.1 \ No newline at end of file