Merge pull request #182 from DFE-Digital/843-rbac-create-cluster-user…

…-groups

[843] Update documentation after AD groups change

README.md

@@ -64,6 +64,12 @@ When creating a brand new cluster with its own configuration, follow these steps
 - Create the new config entry in the Makefile
 - Create low-level terraform resources: `make <config> validate-azure-resources` and `make <config> deploy-azure-resources`
 - Request the Cloud Engineering Team to assign role "Network Contributor" to the new managed identity on the new resource group
+- Create the admin AD group following the [AD groups documentation](https://educationgovuk.sharepoint.com/sites/teacher-services-infrastructure/SitePages/AKS%20AD%20groups.aspx)
+- Use the group object id in the admin_group_id variable
+- Use PIM for groups to activate membership of the admin group
+- Run: `make <environment> terraform-apply`
+- Configure a domain pointing at the new ingress IP following [Cluster DNS zone configuration](#cluster-dns-zone-configuration).
+- Create or update the user AD groups as per the [AD groups documentation](https://educationgovuk.sharepoint.com/sites/teacher-services-infrastructure/SitePages/AKS%20AD%20groups.aspx)
 
 ### kubectl
 - Follow the [kubectl documentation](https://kubernetes.io/docs/tasks/tools/#kubectl) to install it
@@ -130,7 +136,7 @@ Flags = 0, Tag = issue, value =“globalsign.com”
 
 See [terraform configuration](https://github.com/DFE-Digital/terraform-modules/blob/main/dns/zones/resources.tf) or [GlobalSign documentation](https://support.globalsign.com/ssl/general-ssl/how-add-dns-caa-record-dns-zone-file).
 
-1. Navigate to Key Vaults, select the applicable Key vault 
+1. Navigate to Key Vaults, select the applicable Key vault
 1. Either create a new certificate or generate a new version of an existing certificate(the latter is preferred where possible) - Validity is typically left at 12 months
 1. Add caa record list and configuration as shown in https://github.com/DFE-Digital/terraform-modules/blob/main/dns/zones/resources.tf
 
@@ -176,9 +182,21 @@ and the prod zone updated.
 The teacherservices.cloud domain is created in route53 and owned by infra-ops. So if the production zone NS records are changed for any reason, then contact infra-ops to update the domain.
 
 ## Links
+### External
+- [Developer onboarding](documentation/developer-onboarding.md)
+- [Onboard a new service to AKS](documentation/onboard-service.md)
+- [Onboarding form template](documentation/onboard-form-template.md)
+- [Kubernetes cluster Public IPs](documentation/public-ips.md)
+- [Production checklist](documentation/production-checklist.md)
+- [Postgres FAQ](documentation/postgres-faq.md)
+- [Cluster plublic IPs](documentation/public-ips.md)
+
+### Internal
 - [AKS upgrade](documentation/aks-upgrade.md)
 - [Node pool migration](documentation/node-pool-migration.md)
-- [Retrieving Log Analytics Data with KQL for AKS Clusters](documentation/aks-logs.md)
 - [Rebuild AKS cluster with zero downtime](documentation/rebuild-cluster.md)
-- [Onboard a new service to AKS](documentation/onboard-service.md)
-- [Kubernetes cluster Public IPs](documentation/public-ips.md)
+- [Ingress controller upgrade](documentation/Ingress-controller-upgrade.md)
+- [Retrieving Log Analytics Data with KQL for AKS Clusters](documentation/aks-logs.md)
+- [Low priority app](documentation/lowpriority-app.md)
+- [Monitoring](documentation/monitoring.md)
+- [Slack webhook integration](documentation/slack-webhook-integration.md)

documentation/developer-onboarding.md

@@ -11,27 +11,20 @@ Documentation for the Teacher services application developers
 - [kubelogin](https://azure.github.io/kubelogin/install.html)
 
 ## How to request access?
-- There is an assumption that you have been given a [CIP account](https://technical-guidance.education.gov.uk/infrastructure/hosting/azure-cip/#onboarding-users). For BYOD users, please make sure to request a digitalauth account.
-- You can then request access to the S189 subscriptions by contacting the Teacher Services Infrastructure team
-- This gives you access to the 3 s189 subscriptions:
-   - s189-teacher-services-cloud-development: infra team development work
-   - s189-teacher-services-cloud-test: contains the [test cluster](#test-cluster)
-   - s189-teacher-services-cloud-production: contains the [production cluster](#production-cluster)
+- There is an assumption that you have been given a [CIP account](https://technical-guidance.education.gov.uk/infrastructure/hosting/azure-cip/#onboarding-users). For BYOD users, please make sure to request a [digitalauth account](https://educationgovuk.sharepoint.com/sites/teacher-services-infrastructure/SitePages/Request-a-digitalauth-Azure-account.aspx).
+- The technical lead of your team will then add you to the AD group of your area. For example if you work on a BAT service, you will be added to "s189 BAT delivery team". You will now be able to:
+   - Access (read-only) the s189 subscriptions in the [Azure portal](https://portal.azure.com/#home)
+   - Access (read-write) to your test Kubernetes namespaces and Azure resource groups in the _test_ subscription
+   - [Elevate your permissions via PIM](#how-to-request-and-approve-pim) and access (read-write) temporarily the production Kubernetes namespaces and Azure resource groups
+   - Approve other developers' PIM requests
 
-## How to request and approve PIM?
+## How to request PIM?
+Microsoft Entra Privileged Identity Management (PIM) allows gaining temporary (up to 8h) user permissions to access production resources. This is sometimes required to access the Kubernetes cluster and troubleshoot the application or database.
 
-### Access to apps on the cluster
-Microsoft Entra Privileged Identity Management (PIM) allows gaining new user permissions. This is required to access the cluster and troubleshoot application or database. **We must be very cautious** as this gives access to all the other services deployed to s189 subscriptions.
-
-Use [PIM for groups](https://learn.microsoft.com/en-us/entra/id-governance/privileged-identity-management/groups-activate-roles) to elevate your access. Two groups are available:
-- `s189 AKS admin test PIM`: access to the test cluster, self-approved
-- `s189 AKS admin production PIM`: access to the production cluster, must be approved by another team member
-
-### Azure admin access
-- This should only required to edit app secrets or force a deployment. **Be very cautious** as this gives you full permissions on all the Azure resources in the subscription.
-- Once added to the s189 subscription, you can PIM yourself to the *test* subscription. See the [technical guidance PIM section](https://technical-guidance.education.gov.uk/infrastructure/hosting/azure-cip/#privileged-identity-management-pim-requests).
-- You can request PIM to the *production* subscription, however this will need to be approved by members of the Managers group
-- As a manager, you should receive and email with the user request. You can also approve PIM requests by going to [Privileged Identity Management](https://portal.azure.com/?feature.msaljs=true#view/Microsoft_Azure_PIMCommon/CommonMenuBlade/~/quickStart) (PIM) in the Azure portal and selecting Approve request, Azure resources, select the user and approve the request.
+- Use [PIM for groups](https://learn.microsoft.com/en-us/entra/id-governance/privileged-identity-management/groups-activate-roles) to elevate your access. You should see the PIM group of your area. For example if you work on a BAT service, you should see: "s189 BAT production PIM".
+- Click "Activate", select the time and give a brief justification, which is important to gain approval and audit purpose.
+- The other members of the team will receive an email with a link to PIM so they can review and approve your request.
+- After a few minutes, your access will be active. It may require login out and in again.
 
 ## Which clusters can I use?
 The infra team maintains several AKS clusters. Two are usable by developers to deploy their services:
@@ -49,11 +42,11 @@ Used for all your production and production-like environments, especially if the
 - Subscription: `s189-teacher-services-cloud-production`
 
 ## How to access the cluster?
-- If not present in your repository, set up the `get-cluster-credentials` make command from the template [Makefile](https://github.com/DFE-Digital/teacher-services-cloud/blob/main/templates/new_service/Makefile). For Azure RBAC clusters, it must include the *kubelogin convert-kubeconfig* command.
-- Raise a [PIM request](#how-to-request-and-approve-pim) for either the test or production subscription
+- If not present in your repository, set up the `get-cluster-credentials` make command from the template [Makefile](https://github.com/DFE-Digital/teacher-services-cloud/blob/main/templates/new_service/Makefile).
+- If the environment is production, raise a [PIM request](#how-to-request-pim)
 - Login to azure command line using `az login` or `az login --use-device-code`
 - Run `make <environment> get-cluster-credentials`
-- This configures the `kubectl` context so you can run commands against this cluster. Be careful as the context may last even after the PIM has expired.
+- This configures the `kubectl` context so you can run commands against this cluster
 
 ## What is a namespace?
 Namespaces are a way to logically partition and isolate resources within a Kubernetes cluster. Each namespace has its own set of isolated resources like pods, services, deployments etc.
@@ -63,6 +56,8 @@ For instance, you will see:
 - *tra-development* and *tra-staging* on the test cluster
 - *tra-production* on the production cluster
 
+Here is the full list of namespaces [in the test cluster](https://github.com/DFE-Digital/teacher-services-cloud/blob/main/cluster/terraform_kubernetes/config/test.tfvars.json) and [in the production cluster](https://github.com/DFE-Digital/teacher-services-cloud/blob/main/cluster/terraform_kubernetes/config/production.tfvars.json).
+
 *kubectl* commands run in a particular namespace using `-n <namespace>`.
 
 ## Basic commands

documentation/onboard-service.md

@@ -17,7 +17,6 @@ flowchart TD;
 Before starting, it is important to capture the information required upfront using the  [Onboarding form](onboard-form-template.md) even if it is subject to change in the future. Also, its really important to
 check the [Production Checklist](production-checklist.md). Your code should then be ready to roll.
 
-
 ## Template
 Most services use the same code to deploy to AKS. It has been made into a template that will evolve over time to capture all the best practices from working in multiple services.
 It is used both to dramatically reduce the time required to onboard a new service, and be a point of reference to align standards across repositories.
@@ -51,8 +50,8 @@ The code covers most common use cases, but it may be necessary to amend it. Exam
 - The only environment configurations are development and production. The service may need more or use different names.
 - The web application uses `/healthcheck` as health probe. It can be changed to another path or disabled by passing `null`.
 
-## Deploy new service
-In the service repository, runs the Makefile commands.
+## Prepare new environment
+These steps must be done by the infra team.
 
 ### Login to Azure
 Raise a [PIM request](https://technical-guidance.education.gov.uk/infrastructure/hosting/azure-cip/#privileged-identity-management-pim-requests) to either:
@@ -67,6 +66,15 @@ This creates the minimum Azure resources required to run terraform, ie storage a
 - Validate: `make <environment config> validate-arm-resources`. Example: `make development validate-arm-resources`
 - Deploy: `make <environment config> deploy-arm-resources`. Example: `make development deploy-arm-resources`
 
+### Enable developers access
+Amend the AD group of the area:
+- Add the namespaces and resource groups to [the AD groups spreadsheet](https://educationgovuk.sharepoint.com/:x:/r/sites/teacher-services-infrastructure/Shared%20Documents/Azure/Teacher%20services%20AD%20groups.xlsx?d=wd9dfa57ba7a64515af86effd063d450a&csf=1&web=1&e=6MdA98). For instance if the service is in BAT, edit the BAT groups (delivery team and production PIM).
+- [Raise CIP requests](https://dfe.service-now.com.mcas.ms/serviceportal/?id=sc_cat_item&sys_id=51b0b9c5db1ff7809402e1aa4b96197d&referrer=recent_items) to amend the 2 groups
+- The developers should now have access to continue with the set-up
+
+## Deploy new service
+In the service repository, runs the Makefile commands.
+
 ### Configure Statuscake credentials
 If Statuscake is not required at this stage, comment out resources in `terraform/application/statuscake.tf` and the provider in `terraform/application/terraform.tf`.