diff --git a/.github/workflows/publish-dev.yaml b/.github/workflows/publish-dev.yaml index 7e4ac28..31f34f8 100644 --- a/.github/workflows/publish-dev.yaml +++ b/.github/workflows/publish-dev.yaml @@ -6,7 +6,7 @@ on: branches: [ dev ] paths: - "mkdocs.yml" - - "docs/*" + - "docs/**" jobs: test_techdocs_build_job: diff --git a/.github/workflows/publish-prod.yaml b/.github/workflows/publish-prod.yaml index f4977ec..418c03b 100644 --- a/.github/workflows/publish-prod.yaml +++ b/.github/workflows/publish-prod.yaml @@ -6,7 +6,7 @@ on: branches: [ main ] paths: - "mkdocs.yml" - - "docs/*" + - "docs/**" jobs: test_techdocs_build_job: diff --git a/docs/aws/get-started-with-aws/bc-govs-aws-landing-zone-overview.md b/docs/aws/get-started-with-aws/bc-govs-aws-landing-zone-overview.md index 51a02a0..306593d 100644 --- a/docs/aws/get-started-with-aws/bc-govs-aws-landing-zone-overview.md +++ b/docs/aws/get-started-with-aws/bc-govs-aws-landing-zone-overview.md @@ -103,7 +103,7 @@ The AWS Secure Environment Accelerator (ASEA) product provides a security framew The ASEA security framework ensures that you can develop and deploy applications in a secure, compliant, and controlled AWS environment, enabling them to focus on delivering innovative and effective digital services. -For more information, see [AWS Security & Compliance Guardrails](../design-build-and-deploy-an-application/security-guardrails.md). +For more information, see [AWS Security & Compliance Guardrails](./security-guardrails.md). ### Networking diff --git a/docs/aws/design-build-and-deploy-an-application/security-guardrails.md b/docs/aws/get-started-with-aws/security-guardrails.md similarity index 84% rename from docs/aws/design-build-and-deploy-an-application/security-guardrails.md rename to docs/aws/get-started-with-aws/security-guardrails.md index 0c1a0aa..1e319da 100644 --- a/docs/aws/design-build-and-deploy-an-application/security-guardrails.md +++ b/docs/aws/get-started-with-aws/security-guardrails.md @@ -46,29 +46,29 @@ This means: ## Security and compliance 1. Encryption: - - Encryption is mandatory for services like EBS volumes, RDS instances, and EFS file systems - - You can't disable encryption on resources that require it + * Encryption is mandatory for services like EBS volumes, RDS instances, and EFS file systems + * You can't disable encryption on resources that require it This means: - - When creating new S3 buckets, EBS volumes, or RDS instances, you must ensure they are encrypted. The system will enforce this, but be aware that you can't create unencrypted storage resources + * When creating new S3 buckets, EBS volumes, or RDS instances, you must ensure they are encrypted. The system will enforce this, but be aware that you can't create unencrypted storage resources 2. Security services: - - You have limited ability to modify settings for services like GuardDuty, Security Hub, and Macie. + * You have limited ability to modify settings for services like GuardDuty, Security Hub, and Macie. 3. Logging and monitoring: - - You can't modify or delete CloudWatch logs, alarms, and dashboards related to our managed infrastructure - - You can create your own CloudWatch alarms and dashboards, but you can't modify ones that are part of the protected infrastructure + * You can't modify or delete CloudWatch logs, alarms, and dashboards related to our managed infrastructure + * You can create your own CloudWatch alarms and dashboards, but you can't modify ones that are part of the protected infrastructure ## Account management -- You can't perform high-level account actions such as leaving the AWS organization or closing the account -- Creation of new IAM users and groups is restricted. A limited custom service is deployed in your accounts to create IAM users. See [IAM User Service](./iam-user-service.md) for more information +* You can't perform high-level account actions such as leaving the AWS organization or closing the account +* Creation of new IAM users and groups is restricted. A limited custom service is deployed in your accounts to create IAM users. See [IAM User Service](../design-build-and-deploy-an-application/iam-user-service.md) for more information Implications: -- You can't create new IAM users or groups. If you need to onboard new team members or create new roles, you can do that using the [Product Registry](https://registry.developer.gov.bc.ca). See [BC Gov's Product Registry - User management documentation](./user-management.md) for more information -- Be cautious when attaching policies that grant broad permissions. Use the least privilege principle when assigning permissions +* You can't create new IAM users or groups. If you need to onboard new team members or create new roles, you can do that using the [Product Registry](https://registry.developer.gov.bc.ca). See [BC Gov's Product Registry - User management documentation](../design-build-and-deploy-an-application/user-management.md) for more information +* Be cautious when attaching policies that grant broad permissions. Use the least privilege principle when assigning permissions ## Service restrictions @@ -90,4 +90,4 @@ To provide a centralized view of costs across all accounts and projects, the Pub By following these guidelines, you help maintain the security and compliance of our AWS environment. If these limitations significantly impact your work, contact the Public Cloud team for guidance, workarounds, or to request exceptions for critical business needs. -If you have any questions or need assistance, please contact the Public Cloud team at cloud.pathfinder@gov.bc.ca. +If you have any questions or need assistance, please contact the Public Cloud team at . diff --git a/docs/azure/best-practices/azure-ai.md b/docs/azure/best-practices/azure-ai.md index ac0cf04..810888a 100644 --- a/docs/azure/best-practices/azure-ai.md +++ b/docs/azure/best-practices/azure-ai.md @@ -40,3 +40,15 @@ When working with Azure OpenAI, you may need to create a Private Endpoint to res It has been observed in several cases, where the DNS `A-Record` for the Azure OpenAI service is not being created properly in the Private DNS Zone. This can cause issues with the service not being able to resolve the endpoint. If you encounter this issue, please open a [support ticket](../../welcome/support.md) with the Public Cloud Platform support team to investigate and resolve the issue. + +## Regulated Landing Zone compliance + +If you are deploying Azure Cognitive Services, OpenAI, or Machine Learning, there are several Microsoft Enterprise Scale guardrail policies that are enforced that control permitted SKUs, secure authentication through Managed Identities, storage configuration, outbound network access, etc. + +## Monitoring AI + +Microsoft has created an Azure Monitor Workbook that provides a centralized view of the AI services that are being used. This workbook provides insights into the usage, performance, and health of the AI services. It is recommended to use this workbook to monitor the AI services. + +![Azure Monitor OpenAI Insights Workbook](../images/azure-monitor-workbook-openai-insights.png "Azure Monitor OpenAI Insights Workbook") + +For more information, see [Azure OpenAI Insights: Monitoring AI with Confidence](https://techcommunity.microsoft.com/blog/fasttrackforazureblog/azure-openai-insights-monitoring-ai-with-confidence/4026850). diff --git a/docs/azure/best-practices/ci-cd.md b/docs/azure/best-practices/ci-cd.md index e34bc73..43bc24c 100644 --- a/docs/azure/best-practices/ci-cd.md +++ b/docs/azure/best-practices/ci-cd.md @@ -6,12 +6,12 @@ Last updated: **{{ git_revision_date_localized }}** If you are using GitHub Actions for your CI/CD pipeline, consider the following best practices: -* Use [OpenID Connect (OIDC) authentication](#configuring-github-action-oidc-authentication-to-azure) for GitHub Actions to authenticate with Azure. - -* [Self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) on Azure are required to access data storage and database services from GitHub Actions. Public access to these services is not supported. +* Configure [OpenID Connect (OIDC) authentication](#configuring-github-action-oidc-authentication-to-azure) for GitHub Actions to authenticate with Azure. * If using [Terraform](https://www.terraform.io/), be aware of the limitations when [creating Subnets](../best-practices/be-mindful.md#using-terraform-to-create-subnets), and the use of the [AzAPI Terraform Provider](be-mindful.md#azapi-terraform-provider-using-azapi_update_resource). +* [Self-hosted runners](#self-hosted-runners-on-azure) on Azure are required to access data storage and database services from GitHub Actions. Public access to these services is not supported. + ### Configuring GitHub Action OIDC Authentication to Azure To allow GitHub Actions to securely access Azure subscriptions, use OpenID Connect (OIDC) authentication. @@ -23,8 +23,8 @@ Here's a quick summary on how to set it up: 1. The GitHub Identity Provider has already been configured in the Azure subscriptions in your Project Set 2. In your Azure subscription: - - Create an Entra ID application and a service principal - - Add federated credentials for the Entra ID application + - Create an Entra ID Application and a Service Principal + - Add federated credentials for the Entra ID Application - Create GitHub secrets for storing Azure configuration 3. In your GitHub workflows: @@ -33,3 +33,20 @@ Here's a quick summary on how to set it up: - Use the [azure/login](https://github.com/Azure/login) action to exchange the OIDC token (JWT) for a cloud access token This allows GitHub Actions to authenticate to Azure and access resources. + +### Self-Hosted Runners on Azure + +Microsoft has created an [Azure Verified Module (AVM) for CICD Agents and Runners](https://github.com/Azure/terraform-azurerm-avm-ptn-cicd-agents-and-runners). The Public Cloud team has tested this module, and verified that it works within our Azure environment (with a few customizations). + +We have created a dedicated/centralized GitHub repository to provide sample Terraform code for creating various application patterns, and various tools. This repository is called [Azure Landing Zone Samples (azure-lz-samples)](https://github.com/bcgov/azure-lz-samples). + +You can find the sample Terraform code for deploying self-hosted GitHub runners in the `/tools/cicd_self_hosted_agents/` directory. + +!!! info "Pre-requisites" + Please take special note of the pre-requisites listed in the README file in the `/tools/cicd_self_hosted_agents/` directory. It describes the necessary subnets that the self-hosted runners need to be deployed in. + +!!! question "Cross-Subscription Access" + If you plan to deploy the self-hosted runners into a different Azure subscription than where your resources will be deployed (ie. in your **Tools** subscription), you will need to [submit a firewall request](https://citz-do.atlassian.net/servicedesk/customer/portal/3) to the Public Cloud team. This request will allow the self-hosted runners to access the necessary resources in the other subscription. + +!!! note "" + When using the [Azure Verified Module (AVM) for CICD Agents and Runners](https://github.com/Azure/terraform-azurerm-avm-ptn-cicd-agents-and-runners) (or any other modules), Terraform may show that it will remove certain tags from resources. This is because the module is not aware of the tags that are set on the resources. If you want to keep the tags, you can add a `lifecycle` block with the [ignore_changes](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#ignore_changes) feature, to the resource in your Terraform code to ignore the tags. diff --git a/docs/azure/design-build-deploy/networking.md b/docs/azure/design-build-deploy/networking.md index a4f99da..7e58a79 100644 --- a/docs/azure/design-build-deploy/networking.md +++ b/docs/azure/design-build-deploy/networking.md @@ -13,6 +13,8 @@ There are no subnets that are pre-created within the VNet. Each team is responsi For further guidance on creating subnets with associated NSGs (specifically using Terraform), refer to the [Be Mindful](../best-practices/be-mindful.md#using-terraform-to-create-subnets) documentation. + Additionally, as part of implementing a **Zero Trust** security model, all subnets need to be created as [Private Subnets](https://learn.microsoft.com/en-us/azure/virtual-network/ip-services/default-outbound-access#utilize-the-private-subnet-parameter-public-preview). + ## Spoke-to-Spoke connectivity If your team has multiple environments (ie. Dev, Test, Prod, Tools) within the same Project Set, you may require connectivity between the different environments. This is known as spoke-to-spoke connectivity. diff --git a/docs/azure/images/azure-monitor-workbook-openai-insights.png b/docs/azure/images/azure-monitor-workbook-openai-insights.png new file mode 100644 index 0000000..b02b39f Binary files /dev/null and b/docs/azure/images/azure-monitor-workbook-openai-insights.png differ diff --git a/docs/images/support/project-set-license-plate-example-aws.png b/docs/images/support/project-set-license-plate-example-aws.png new file mode 100644 index 0000000..5c865ae Binary files /dev/null and b/docs/images/support/project-set-license-plate-example-aws.png differ diff --git a/docs/images/support/project-set-license-plate-example-azure.png b/docs/images/support/project-set-license-plate-example-azure.png new file mode 100644 index 0000000..2d14b5f Binary files /dev/null and b/docs/images/support/project-set-license-plate-example-azure.png differ diff --git a/docs/welcome/support.md b/docs/welcome/support.md index 43b1d80..8cd2d7c 100644 --- a/docs/welcome/support.md +++ b/docs/welcome/support.md @@ -2,6 +2,32 @@ Last updated: **{{ git_revision_date_localized }}** +## Project Set license plate + +When requesting support, please provide the 6-character alphanumeric Project Set **license plate**. This is a unique identifier for your Project Set that helps us provide support more efficiently. + +### AWS + +To find the license plate for an AWS Project Set, follow these steps: + +1. Log in to the [AWS Management Console](https://aws.amazon.com/console/). +2. The alphanumeric code in the **Account** column is the license plate for your Project Set. + +![AWS Project Set License Plate](../images/support/project-set-license-plate-example-aws.png "AWS Project Set License Plate") + +### Azure + +To find the license plate for an Azure Project Set, follow these steps: + +1. Log in to the [Azure Portal](https://portal.azure.com/). +2. Search for **Management Groups**. +3. Expand **BCGov-Managed-LZ** > **BCGov-Managed-LZ-Live** > **Landing Zones** and locate your Project Set's Management Group. +4. The alphanumeric code in the **Name** column (for the Management Group, or Subscription) is the license plate for your Project Set. + + - If your Management Group or Subscription name has been changed, the Management Group ID field will contain the original license plate. + +![Azure Project Set License Plate](../images/support/project-set-license-plate-example-azure.png "Azure Project Set License Plate") + ## Support options There are multiple ways to get support for the Public Cloud Platform, including: diff --git a/mkdocs.yml b/mkdocs.yml index a5b3b4f..f940381 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,6 +13,7 @@ nav: - Get started with AWS: - Overview: aws/index.md - AWS Landing Zone overview: aws/get-started-with-aws/bc-govs-aws-landing-zone-overview.md + - AWS Security and compliance guardrails: aws/get-started-with-aws/security-guardrails.md - Design, build, and deploy: - Requirements: aws/design-build-and-deploy-an-application/requirements-for-building-your-application.md - User Management: aws/design-build-and-deploy-an-application/user-management.md @@ -44,9 +45,9 @@ nav: - Azure Cost Management: azure/understanding-your-bill/azure-billing-and-cost-management.md - Upcoming features: - Domain Join: azure/upcoming-features/domain-join.md - - Express route: azure/upcoming-features/express-route.md + - Express route: azure/upcoming-features/express-route.md - Enterprise support: - Azure Enterprise Support: azure/support/enterprise-support.md plugins: - techdocs-core - - git-revision-date-localized + - git-revision-date-localized