update AP quicksight guidance to include embedding

source/documentation/tools/quicksight/01-index.md

@@ -24,6 +24,7 @@ We currently have each of the [domains/business areas](/tools/create-a-derived-t
 - [Finding datasets](/tools/quicksight/working-with-quicksight.html#finding-datasets)
 - [Publishing dashboards](/tools/quicksight/working-with-quicksight.html#publishing-dashboards)
 - [Sharing dashboards](/tools/quicksight/working-with-quicksight.html#sharing-dashboards)
+- [Embedding dashboards](/tools/quicksight/working-with-quicksight.html#embedding-a-dashboard-in-a-cloud-platform-app)
 
 ## [FAQs](/tools/quicksight/faqs.html)
 

source/documentation/tools/quicksight/03-working-with-quicksight.md

@@ -49,6 +49,175 @@ However, after you publish a dashboard, you can share it with other users or gro
 You can also choose to share the dashboard with everyone in your QuickSight account and make the dashboard visible on the QuickSight homepage for all users in your account. 
 Additionally, you can copy a link to the dashboard to share with others who have access to it."
 
+## Embedding a dashboard in a Cloud Platform app
+
+1. Create a new service account and IRSA in your app's cloud platform namespace. You can use [this terraform module](https://github.com/ministryofjustice/cloud-platform-terraform-irsa) and the policy should allow you to assume a role (which also needs creating) in the quicksight aws account, where the role_name in the below is the name of the role that will be created in the quicksight aws account. When this IRSA is created it will be saved in the secrets of your namespace
+
+    <details>
+    <summary>Click here to see an example terraform code block</summary>
+    <pre>
+    <code>
+    module "quicksight_irsa" {
+        source = "github.com/ministryofjustice/cloud-platform-terraform-irsa?ref=2.0.0"
+        eks_cluster_name      = var.eks_cluster_name
+        namespace             = var.namespace
+        service_account_name  = "my-cp-app-quicksight"
+        role_policy_arns = {
+            quicksight = aws_iam_policy.my_cp_app_quicksight.arn
+        }
+        # Tags 
+        business_unit          = var.business_unit
+        application            = var.application
+        is_production          = false
+        environment_name       = var.environment
+        team_name              = var.team_name
+        infrastructure_support = "[email protected]"
+    }
+    data "aws_iam_policy_document" "my_cp_app_quicksight" {
+        statement {
+            effect = "Allow"
+            actions = [
+                "sts:TagSession",
+                "sts:AssumeRole"
+            ]
+            resources = [
+                "arn:aws:iam::{account_id}:role/{role_name}"
+            ]
+        }
+    }
+    resource "aws_iam_policy" "my_cp_app_quicksight" {
+        name   = "my-cp-app-quicksight"
+        policy = data.aws_iam_policy_document.my_cp_app_quicksight.json
+        tags = {
+            business-unit          = var.business_unit
+            application            = var.application
+            is-production          = false
+            environment-name       = var.environment
+            owner                  = var.team_name
+            infrastructure-support = "[email protected]"
+        }
+    }
+    resource "kubernetes_secret" "irsa" {
+        metadata {
+        name      = "quicksight-irsa-output"
+        namespace = var.namespace
+        }
+        data = {
+            role           = module.quicksight_irsa.role_name
+            rolearn        = module.quicksight_irsa.role_arn
+            serviceaccount = module.quicksight_irsa.service_account.name
+        }
+    }
+    </code>
+    </pre>
+    </details>
+
+
+2. You will need to find out the arn, dashboard ID and quicksight namespace for the dashboard that you want to embed, as these will be needed for the policy you'll create in the next step. You can get these by asking in the #ask-analytical-platform slack channel.
+
+3. Create an IAM role in the AP compute account in terraform via the [modernisation platform environments repository](https://github.com/ministryofjustice/modernisation-platform-environments/tree/main/terraform/environments/analytical-platform-compute).
+
+    The iam role should be defined in the iam-roles.tf file
+
+    <details><summary>Click here to see an example terraform code block</summary>
+    <pre>
+    <code>
+        ...
+    </code>
+    </pre>
+    </details>
+
+
+4. Add your new service account to your apps deployment yaml manifest file, so the IAM roles are available to your application. Your service account name can be decoded from the `quicksight_irsa` secret you've previously created.
+
+    <details>
+    <summary>Click here to see an example yaml code block</summary>
+    <pre>
+    <code>
+    apiVersion: apps/v1
+    kind: Deployment
+    metadata:
+        name: my-cp-app
+    spec:
+        replicas: 1
+        selector:
+        matchLabels:
+            app: my-cp-app
+        template:
+        metadata:
+            labels:
+            app: my-cp-app
+        spec:
+            serviceAccountName: <serviceaccount>
+            containers:
+            - name: my-cp-app
+            image: ${IMAGE_PATH}
+            ports:
+            - containerPort: 4567
+    </code>
+    </pre>
+    </details>
+
+5. The Analytical Platform team will need to add your allowed domains to quicksight via the console in AWS - request this via the #ask-analytical-platform slack channel.
+
+6. You should now be able to write code in your app to generate and return a url which can be embedded within a page of your application. 
+    <details>
+    <summary>Click here to see an example Python code block</summary>
+
+    ```python
+    import logging
+    import boto3
+    from botocore.exceptions import ClientError
+    from django.conf import settings
+
+
+    def get_quicksight_client():
+        sts = boto3.client("sts")
+        role_response = sts.assume_role(
+            RoleArn=settings.QUICKSIGHT_ROLE_ARN, RoleSessionName="quicksight"
+        )["Credentials"]
+
+        session = boto3.Session(
+            aws_access_key_id=role_response["AccessKeyId"],
+            aws_secret_access_key=role_response["SecretAccessKey"],
+            aws_session_token=role_response["SessionToken"],
+        )
+
+        return session.client("quicksight")
+
+
+    def generate_embed_url_for_anonymous_user() -> str | None:
+        """
+        Generates an embed URL for an anonymous user to access a QuickSight dashboard.
+
+        Returns:
+            str | None: The embed URL if successful, otherwise None.
+        """
+        quicksight_client = get_quicksight_client()
+        try:
+            response = quicksight_client.generate_embed_url_for_anonymous_user(
+                AwsAccountId=settings.QUICKSIGHT_ACCOUNT_ID,
+                Namespace=settings.QUICKSIGHT_NAMESPACE,
+                AuthorizedResourceArns=[settings.QUICKSIGHT_METADATA_DASHBOARD_ARN],
+                ExperienceConfiguration={
+                    "Dashboard": {
+                        "InitialDashboardId": settings.QUICKSIGHT_METADATA_DASHBOARD_ID
+                    }
+                },
+                SessionLifetimeInMinutes=600,
+            )
+
+            return response["EmbedUrl"]
+
+        except ClientError as e:
+            logging.error(
+                f"Failed to generate embed URL for anonymous user: {e.response['Error']['Message']}"
+            )
+            return None
+    ```
+
+    </details>
+
 <!-- External links -->
 
 [the advice from AWS]: https://docs.aws.amazon.com/quicksight/latest/user/create-a-data-source.html