diff --git a/docs/internal-developer-portal/smp/_category_.json b/docs/internal-developer-portal/smp/_category_.json new file mode 100644 index 00000000000..e7ec8b57899 --- /dev/null +++ b/docs/internal-developer-portal/smp/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Self Managed Platform [BETA]", + "position": 7, + "link": { + "type": "generated-index", + "description": "Documentation for integrating and using Harness Internal Developer Portal with Self Managed Platform" + } + } \ No newline at end of file diff --git a/docs/internal-developer-portal/smp/idp-onboarding.md b/docs/internal-developer-portal/smp/idp-onboarding.md new file mode 100644 index 00000000000..d95cf5852cb --- /dev/null +++ b/docs/internal-developer-portal/smp/idp-onboarding.md @@ -0,0 +1,223 @@ +--- +title: IDP Onboarding to SMP Environments [BETA] +sidebar_position: 2 +sidebar_label: Onboarding Guide +description: Guide for configuring and deploying Harness IDP in Self Managed Platform environments +--- + +# IDP Onboarding to SMP Environments + +:::info Harness IDP SMP Edition [BETA] +Harness IDP Self-Managed Platform (SMP) Edition is currently in **BETA**. Please refer to the [Harness IDP Release Notes](/release-notes/internal-developer-portal) to keep track of new feature updates and improvements. +::: + +This guide provides detailed instructions for deploying the Harness Internal Developer Portal (IDP) to your Self Managed Platform (SMP) environment. Following these configuration steps will help you establish a properly functioning IDP implementation integrated with your SMP infrastructure. + +:::info Only for IDP 2.0 +Harness IDP on SMP is available only for **IDP 2.0**. **IDP 1.0** is **not supported** on SMP. +::: + +--- + +## Overview + +## Infrastructure Requirements + +Before proceeding with the IDP deployment to SMP, ensure the following prerequisites are met: + +1. **Workload Identity** enabled on the target GKE cluster : + Workload Identity allows your Kubernetes workloads to securely access Google Cloud services with fine-grained IAM permissions. [Configure Workload Identity in your GKE cluster](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) following Google's [security best practices](https://cloud.google.com/blog/products/containers-kubernetes/introducing-workload-identity-better-authentication-for-your-gke-applications). + +2. **Kubernetes Service Account (KSA)** with developer-level permissions + Create a [Kubernetes Service Account](https://kubernetes.io/docs/concepts/security/service-accounts/) that will be linked to your Google Service Account with the Kubernetes Engine Developer role. For GKE-specific guidance, see [Managing Service Accounts](https://cloud.google.com/kubernetes-engine/docs/how-to/kubernetes-service-accounts). + +3. **Service Account token** for TechDocs integration : + The TechDocs component requires a service account token to access and render documentation properly. + +:::warning Network/Firewall Requirement +If your setup integrates with third-party SaaS products (for example, PagerDuty, GitHub, or GitLab), you must whitelist their domains in your firewall policies. + +**PagerDuty example** +- **FQDNs:** `harness.pagerduty.com` +- **Protocol/Ports:** `tcp:80`, `tcp:443` +::: + +### Identity Configuration + +**Step 1: Bind the KSA to the GSA** + +Configure the Kubernetes Service Account (KSA) to impersonate the Google Service Account (GSA) using the following command: + +```bash +gcloud iam service-accounts add-iam-policy-binding \ + @.iam.gserviceaccount.com \ + --member="serviceAccount:.svc.id.goog[/]" \ + --role=roles/iam.workloadIdentityUser \ + --project= +``` + +**Step 2: Annotate the Kubernetes Service Account** + +Add the appropriate annotation to the Kubernetes Service Account to establish the mapping to the Google Service Account: + +```bash +kubectl annotate serviceaccount \ + --namespace \ + iam.gke.io/gcp-service-account=@.iam.gserviceaccount.com \ + --overwrite +``` + +:::note Additional Resources +For more detailed information about Workload Identity, refer to Google's [official documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity). +::: + +## IDP Configuration Process + +Follow these steps to configure and deploy IDP in your SMP environment. Each step includes example configurations that should be adapted to your specific environment. + +### Step 1: Enable IDP Globally + +Update the `harness-values.yaml` file to enable IDP at the global configuration level: + +```yaml +--- +global: + idp: + enabled: true +``` + +### Step 2: Configure Next-Gen UI Integration + +Configure the Next-Gen UI to connect with your IDP service by adding the following to your `harness-values.yaml`: + +```yaml +platform: + next-gen-ui: + config: + IDP_URL: "https://" + # Example: https://35.224.109.55 +``` + +:::tip Important +Document the loadbalancer IP address as it will be required for subsequent configuration steps and potential troubleshooting. +::: + +### Step 3: Configure the IDP App UI + +Update the `idp-app-ui` section in the `harness-values.yaml` file with the appropriate values for your environment: + +```yaml +idp: + idp-app-ui: + app_base_url: https:////ng/account//module/idp + # eg - https://smp.harness.io/smpairgap/ng/account/abc123xyz789acct/module/idp + backend_base_url: https://harness-ingress-controller..svc.cluster.local//idp + # Example - https://harness-ingress-controller.smpairgap.svc.cluster.local/abc123xyz789acct/idp + backend_cors_origin: https:// + # Example - https://smp.harness.io + gcs_bucket_name: + # Example - idp-techdocs-bucket + idp_account_id: + # Example - abc123xyz789acct + idp_namespace: + # Example - smpairgap + secrets: + fileSecret: + - keys: + - key: techdocs_gcs_sa + path: idp-play.json + # Example - service account key file for GCS TechDocs backend + volumeMountPath: /app/gcs + # Example - path inside container where file secret is mounted + secretManagement: + externalSecretsOperator: + - remoteKeys: + techdocs_gcs_sa: + name: + # Example: TECH_DOCS_SECRET + # This references the Service Account token from Infrastructure Requirement #3 + secretStore: + kind: ClusterSecretStore + # Example: ClusterSecretStore + name: + # Example: project +``` + +:::caution URL Configuration +URLs must be precisely configured as mismatches are a common source of deployment issues. Verify all URL paths and formats before applying the configuration. +::: + +### Step 4: Configure IDP Service Backend + +Configure the IDP service backend components with the following settings in your `harness-values.yaml`: + +```yaml +idp-service: + config: + BACKSTAGE_BASE_URL: https://harness-ingress-controller..svc.cluster.local + # Example: https://harness-ingress-controller.smpairgap.svc.cluster.local + DEPLOYMENT_NAMESPACE: + # Example: smpairgap + ENVIRONMENT_BASE_URL: https:// + # Example: https://smp.harness.io + + # The following three settings reference the GKE cluster with Workload Identity enabled from Infrastructure Requirement #1 + IDP_APP_PRIMARY_WORKLOAD_IDENTITY_CLUSTER: + # Example: smp-gke-cluster + IDP_APP_PRIMARY_WORKLOAD_IDENTITY_LOCATION: + # Example: us-central1 + IDP_APP_PRIMARY_WORKLOAD_IDENTITY_PROJECT: + # Example: harness-techdocs-demo + # Optional if we want to use any other service account. + serviceAccount: + create: false + name: harness-default + # Example: harness-default +``` + +The IDP service will leverage the Workload Identity configuration from earlier steps to access Google Cloud resources securely. + +## Troubleshooting + +If you encounter issues during the deployment process, use these troubleshooting approaches to identify and resolve common problems. + +#### 403 Error in idp-service Logs + +This error indicates missing permissions or incorrect service account configuration: + +``` +java.io.IOException: Unexpected Error code 403 trying to get security access token from Compute Engine metadata +``` + +**Resolution:** Verify the service account bindings and annotations from the identity configuration steps. Common causes include typographical errors in project IDs or namespaces. + +#### Environment Configuration Verification + +Verify proper environment configuration by examining the `idp-service` logs for expected values: + +> Env: SMP, DeploymentType: SMP and DeploymentNamespace: `` + +``` +Env: SMP DevSpaceDefaultBackstageNamespace: envSpecific DevSpaceDefaultAccountId: envSpecific DeploymentType: SMP DeploymentNamespace: smpnamespace +``` + +These values should align with your intended configuration. Mismatches indicate configuration issues that need correction. + +#### Database Configuration Validation + +In the idp-service database, confirm that: + +1. The `backstageNamespace` collection mongoID matches the namespace provided in the `idp-service` config +2. The `accountIdentifier` matches the account ID of the SMP environment + + +Discrepancies in these values can cause operational issues with your IDP deployment. + +#### Master URL Verification + +Check the Master URL values in the `idp-service` logs: + +- Primary cluster: Master URL should be `https://kubernetes.default.svc` +- Failover cluster: Master URL should be `dummy` + +If the Master URL appears as `null`, this indicates an infrastructure configuration issue, such as missing annotations, incorrect service account roles, or insufficient permissions. diff --git a/docs/internal-developer-portal/smp/static/smp-release-1.png b/docs/internal-developer-portal/smp/static/smp-release-1.png new file mode 100644 index 00000000000..1c441928eb3 Binary files /dev/null and b/docs/internal-developer-portal/smp/static/smp-release-1.png differ diff --git a/docs/internal-developer-portal/smp/whats-supported.md b/docs/internal-developer-portal/smp/whats-supported.md new file mode 100644 index 00000000000..ab713a7ffb4 --- /dev/null +++ b/docs/internal-developer-portal/smp/whats-supported.md @@ -0,0 +1,106 @@ +--- +title: Overview & What's Supported +sidebar_position: 1 +sidebar_label: Overview & What's Supported +description: Guide for configuring and deploying Harness IDP in Self Managed Platform environments +--- + +:::info Harness IDP SMP Edition [BETA] +Harness IDP Self-Managed Platform (SMP) Edition is currently in **BETA**. Please refer to the [Harness IDP Release Notes](/release-notes/internal-developer-portal) to keep track of new feature updates and improvements. +::: + +## Harness IDP SMP Edition +[Harness Self-Managed Enterprise Edition](https://developer.harness.io/docs/self-managed-enterprise-edition/smp-overview) is an on-premises solution that allows you to install and run Harness on your own infrastructure. It gives you full control over data, security, and compliance while leveraging Harness’s software delivery capabilities. **Harness IDP** is available for the **Self-Managed Enterprise Edition**. This means you can use Harness IDP with the SMP version on your own infrastructure. + +:::info Only for IDP 2.0 +Harness IDP on SMP is available only for **IDP 2.0**. **IDP 1.0** is **not supported** on SMP. +::: + +### Architecture + +![](./static/smp-release-1.png) + +#### PostgreSQL Databases created by IDP + +IDP creates multiple **per-plugin databases** in PostgreSQL. Each database name is **prefixed with your Harness account ID**. + +**Typical Databases** + +* `accountId_app` +* `accountId_auth` +* `accountId_catalog` +* `accountId_devtools` +* `accountId_layout` +* `accountId_permission` +* `accountId_proxy` +* `accountId_scaffolder` +* `accountId_search` +* `accountId_sonarqube` +* `accountId_techdocs` + +> **Note:** The exact set can vary based on which plugins are enabled. Some plugins may create their **own additional databases**. + +#### PostgreSQL Configuration +- If `postgresql.enabled` is `true` in your setup, IDP will reuse the **in-cluster PostgreSQL instance** and default chart credentials will be used automatically. +- If `postgresql.enabled` is `false`, provide external PostgreSQL credentials in the following format: +``` +postgres: + ## - protocol to use for connection + protocol: '' + ## - host array for external + hosts: [] + extraArgs: '' + secrets: + kubernetesSecrets: + - secretName: '' + keys: + POSTGRES_USER: '' + POSTGRES_PASSWORD: '' + secretManagement: + externalSecretsOperator: + - secretStore: + name: '' + kind: '' + remoteKeys: + POSTGRES_USER: + name: '' + property: '' + POSTGRES_PASSWORD: + name: '' + property: '' +``` + +--- + +## Supported Infrastructure +The Self-Managed Enterprise Edition runs within the customer’s environment alongside existing services. You must have a Kubernetes cluster with a configured load balancer. Harness IDP is supported on SMP only when the control plane is deployed on **Google Cloud Platform (GCP)** using **Google Kubernetes Engine (GKE)**. Deployments on AWS (EKS), Azure (AKS), on-prem, or OpenShift are **not supported**. + +:::warning Network/Firewall Requirement +If your setup integrates with third-party SaaS products (for example, PagerDuty, GitHub, or GitLab), you must whitelist their domains in your firewall policies. + +**PagerDuty example** +- **FQDNs:** `harness.pagerduty.com` +- **Protocol/Ports:** `tcp:80`, `tcp:443` +::: + +--- + +## Supported Features + +The following features are supported for Harness IDP SMP Edition: + +| **Feature** | **Status in SMP** | **Notes** | +|--------------------------|-------------------|------------------------------| +| Catalog | ✅ | | +| Self Service Workflows | ✅ | | +| Scorecards | ✅ | | +| Git Experience | ✅ | | +| Environment Management | ❌ | Not supported in SMP edition | +| Plugins | ✅ | | +| TechDocs | ❌ | Not supported in SMP edition | +| RBAC | ✅ | | + +--- + +## Next Steps +Go to [Onboarding Guide](/docs/internal-developer-portal/smp/idp-onboarding.md) to learn how to deploy Harness IDP on SMP. \ No newline at end of file diff --git a/sidebars.ts b/sidebars.ts index 4cbe8532d55..cf43c02f720 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -3186,6 +3186,16 @@ const sidebars: SidebarsConfig = { ' Troubleshooting & Resources ', className: 'horizontal-bar', }, + { + type: "category", + label: "Self Managed Platform", + link: { + type: "generated-index", + description: "Documentation for integrating and using Harness Internal Developer Portal with Self Managed Platform" + }, + collapsed: true, + items: [ { type: "autogenerated", dirName: "internal-developer-portal/smp", } ], + }, { type: 'category', label: 'Troubleshoot & FAQs',