From cb9bdba6ed70628fe4d16cb069aabca63542da0d Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Mon, 13 Jan 2025 12:07:08 +0300 Subject: [PATCH 01/40] added k8s migration document --- .../configuration/docker-k8s-migration.md | 450 ++++++++++++++++++ 1 file changed, 450 insertions(+) create mode 100644 docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md new file mode 100644 index 000000000..092b20be9 --- /dev/null +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md @@ -0,0 +1,450 @@ +--- +title: Docker to Kubernetes Migration +description: Learn how to migrate from standalone Appcircle server to Kubernetes Appcircle server. +tags: [self-hosted, helm, configuration, kubernetes, migration] +sidebar_position: 95 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +This guide provides a comprehensive walkthrough for migrating your self-hosted Appcircle instance from a Docker environment to a Kubernetes cluster. It assumes you have a working Docker deployment of Appcircle and a Kubernetes cluster ready for deployment. + +In this migration guide, the "bastion host" refers to a machine that has network access to both your existing standalone Appcircle server (running on Docker) and your Kubernetes cluster. It serves as a central point for executing commands on the Docker host, saving the backup data, and then interacting with the Kubernetes cluster to deploy and configure the new Appcircle instance. You'll copy configuration files and database backups from the Docker host to this bastion host, and then use this host to apply the configuration and data to the Kubernetes cluster. + +:::caution +This migration process involves downtime. Plan accordingly and back up all crucial data before proceeding. Ensure you understand the implications of each step. Test the migration in a staging environment first if possible. +::: + +## Pre-Migration + +### 1. Backup Standalone Appcircle Server + +This section outlines the necessary steps to prepare for the migration. You will back up crucial data from your existing Docker-based Appcircle installation and set up your Kubernetes environment for the new deployment. + +This involves creating a central directory on a bastion host, backing up configuration files and databases, and preparing your Kubernetes cluster. + +:::tip +Before proceeding, it is **highly recommended** to create a full backup of your Appcircle server. This provides an extra layer of safety in case anything goes wrong during the migration. This might involve creating a snapshot of the Docker VM or using a backup tool specific to your setup. +::: + +- **Create a Migration Directory:** On your **bastion host**, create a directory to store backup files: + +```bash +mkdir appcircle-k8s-migration && cd appcircle-k8s-migration +``` + +- **Backup Appcircle Data (Docker):** On your standalone Appcircle server, execute the following commands and copy the output to your bastion host: + + - **Global Configuration:** Save the content to a file named `global.yaml` on the bastion host. + + ```bash + cd appcircle-server + cat projects//global.yaml + ``` + + - **User Secrets:** Save the content to a file named `user-secret.yaml` on the bastion host. + + ```bash + cat projects//user-secret | base64 -d + ``` + + - **Generated Secrets:** Save the content to a file named `generated-secret.yaml` on the bastion host. + + ```bash + cat projects//generated-secret.yaml + ``` + + - **Credentials (if using Google Artifact Registry):** + + ```bash + cat cred.json + ``` + +### 2. Deploy the Appcircle Server to the Kubernetes + +Please follow the [Kubernetes](/self-hosted-appcircle/install-server/helm-chart/installation/kubernetes.md) documentation for detailed Appcircle server installation documents. + +There are some points that you should pay attention: + +- If the standalone Appcircle server is running `HTTP` instead of `HTTPS`, you should configure the Helm chart configuration for `HTTP`. +- Check the standalone Appcircle disk usage. The stateful apps such as MinIO, MongoDB etc should have at least that much data. + +### 3. Make Sure the Standalone Appcircle Server Is Running + +Make sure that the Appcircle server is up and running without any problem. + +### 4. Check the Data Size on the Standalone Appcircle Server + +- Get the volume sizes: + +```bash +export APPCIRCLE_DISK_USAGE=$(docker system df -v) +``` + +- Check the MinIO data size: + +```bash +echo "$APPCIRCLE_DISK_USAGE" | grep "snsd_data" +``` + +- Check the MongoDB data size: + +```bash +echo "$APPCIRCLE_DISK_USAGE" | grep "mongo_data" +``` + +- Check the PostgreSQL data size: + +```bash +echo "$APPCIRCLE_DISK_USAGE" | grep "posgresqlData" +``` + +- Check the Vault data size: + +```bash +echo "$APPCIRCLE_DISK_USAGE" | grep "vault_data" +``` + +- Adjust the Helm `values.yaml` according to standalone Appcircle server data sizes. For more detailed information, please check [Storage Configuration](/self-hosted-appcircle/install-server/helm-chart/configuration/storage-configuration.md) + +## Migrate the Data + +### 1. Create Kubernetes Secrets + +This section details the creation of Kubernetes secrets required for Appcircle to function correctly. These secrets store sensitive information such as passwords, and certificates, securely injecting them into your Appcircle deployment. + +:::tip +Ensure you have [gathered all necessary data](#pre-migration-backup-and-preparation) before proceeding. + +Some secret data, such as database passwords and Keycloak client secrets, used in the Kubernetes secrets creation below should match the data extracted from the backups of the standalone server. Ensure consistency between the backed-up values and the values used in the Kubernetes secrets to prevent connectivity and authentication issues. +::: + +- **Kubernetes Namespace:** Create a namespace for Appcircle in your Kubernetes cluster: + + ```bash + kubectl create namespace appcircle + ``` + +- **Container Registry Secret:** Create the container registry secret for Appcircle artifact registry: + +:::info +If you are using your own container registry, follow the `Custom Registry` section below. + +If your registry doesn't require authentication, you can skip this section. +::: + + + + + +- Save the `cred.json` file. + +- Create the container registry secret: + +```bash +kubectl create secret docker-registry containerregistry \ + -n appcircle \ + --docker-server='europe-west1-docker.pkg.dev' \ + --docker-username='_json_key' \ + --docker-password="$(cat cred.json)" +``` + + + + +- Update the `server`, `username`, and `password` fields for your own custom registry and create the container registry secret: + +```bash +kubectl create secret docker-registry containerregistry \ + -n appcircle \ + --docker-server='registry.spacetech.com' \ + --docker-username='yourRegistryUsername' \ + --docker-password='superSecretRegistryPassword' +``` + + + + +- **SMTP Password Secret:** Create the SMTP server password if the SMTP server that the Appcircle server will use requires authentication. + +```bash +kubectl create secret generic appcircle-server-smtp \ + -n appcircle \ + --from-file=password= +``` + +- **Keycloak Clients Secret:** Create the Keycloak client secrets. + +:::caution +The client secret values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.clients` key on the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. +::: + +```bash +kubectl create secret generic appcircle-server-auth-keycloak-clients-secret \ + -n appcircle \ + --from-literal=appcircleWeb='dc589939-******-87b57fc1a1c7' \ + --from-literal=buildServer='307f6946-******-9d7743294f6a' \ + --from-literal=distributionAdminService='a286d519-******-227dec040f53' \ + --from-literal=distributionTesterWeb='7cc0c02a-******-5e7139d63f3c' \ + --from-literal=licenseServer='e198b11a-******-1ac96174d6f7' \ + --from-literal=publishServer='7965798e-******-0b4e8af8afed' \ + --from-literal=reportingServer='88e3abfd-******-afd2e2a1263f' \ + --from-literal=storeAdminService='f263f48f-******-588c9f55b4e3' \ + --from-literal=storeServer='08839b8d-******-aff4ecb63703' \ + --from-literal=storeWeb='9f6a406e-******-a88c17d7c2f6' \ + --from-literal=distributionServer='7cc0c02a-******-5e7139d63f3c' +``` + +- **Keycloak Passwords Secret:** + +:::caution +The keycloak password values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.password` key for the `adminPassword` and `.keycloak.initialPassword` for the `initialPassword` on the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. +::: + +```bash +kubectl create secret generic appcircle-server-auth-keycloak-passwords \ + -n appcircle \ + --from-literal=initialPassword= \ + --from-literal=adminPassword= +``` + +- **SSL Certificate Secret:** If you are using the Appcircle with HTTPS, create secret for SSL certificates. + +```bash +kubectl create secret generic appcircle-tls-wildcard \ + -n appcircle \ + --from-file=tls.crt= \ + --from-file=tls.key= \ + --from-file=ca.crt= \ + --type=kubernetes.io/tls +``` + +- **MinIO Connection Secret:** Extract the `secretKey` from `generated-secret.yaml`. + +:::caution +The MinIO keys used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.password` key for the `adminPassword` and `.keycloak.initialPassword` for the `initialPassword` on the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. +::: + +```bash +kubectl create secret generic appcircle-server-minio-connection \ + -n appcircle \ + --from-literal=accessKey=admin \ + --from-literal=secretKey= \ + --from-literal=root-user=admin \ + --from-literal=root-password= +``` + +### 2. PostgreSQL Backup & Restore + +#### Standalone Appcircle Server + +1. **Locate PostgreSQL Container:**: Find the PostgreSQL container name. + ```bash + docker ps | grep postgres + ``` +2. **Dump Database:** + + Most likely the username is `keycloak` and the database is `keycloak`. + + ```bash + docker exec pg_dump -U -h localhost -p 5432 -F c -b -v -f pgdump.backup + ``` + +3. **Copy Dump:** + ```bash + docker cp :/pgdump.backup ~/appcircle-k8s-migration/ + ``` + +#### Bastion Host + +1. **Copy the PostgreSQL Data to Bastion Host**: Copy the dumped PostgreSQL data from the Appcircle server to the bastion host. + +2. **Get PostgreSQL Password:** + + ```bash + kubectl get secret -n appcircle appcircle-server-auth-postgresql -ojsonpath='{.data.password}' | base64 -d + ``` + +3. **Get the PostgreSQL pod name:** + + ```bash + kubectl get pods -n appcircle | grep postgres + ``` + +4. **Start Port Forwarding:** + + ```bash + kubectl port-forward appcircle-server-auth-postgresql-0 5432:5432 -n appcircle + ``` + +5. **Install PostgreSQL tools:** + + ```bash + brew install postgresql + ``` + +6. **Restore Database:** + + ```bash + pg_restore -h localhost -p 5432 -U -d ~/appcircle-k8s-migration/pgdump.backup + ``` + +### 3. MongoDB Backup & Restore + +#### Standalone Appcircle Server + +1. **Expose MongoDB Port:** Add a port mapping (e.g., 36300:36300) to your `docker-compose.yml` for the `mongo_1` service and restart. + + ```bash + vim projects/spacetech/export/compose.yaml + ``` + + ```yaml + services: + mongo_1: + image: europe-west1-docker.pkg.dev/appcircle/docker-registry/mongo:v3.25.0 + ports: + - "36300:36300" + ``` + +2. **Get the MongoDB connection string:** + + ```bash + cat projects/spacetech/export/publish/default.env | grep CUSTOMCONNSTR_PUBLISH_DB_CONNECTION_STRING + ``` + +#### Bastion Host + +1. **Install mongo tools:** + + ``` + brew tap mongodb/brew + brew install mongosh + brew install mongodb-database-tools + ``` + +2. **Open Mongo Shell to the standalone Appcircle server:** + + ``` + mongosh --host 192.168.1.220 --port 36300 + ``` + +3. **Switch to the `admin` db:** + + ``` + use admin + ``` + +4. **Create a user to dump the DB:** + ``` + db.createUser({user: "backup",pwd: "backup",roles: [{ role: "root", db: "admin"}]}) + ``` + +#### Standalone Appcircle Server + +1. **Get the MongoDB container names:** + ``` + docker ps | grep mongo_1 + ``` +2. **Dump the MongoDB:** + + ``` + docker exec -it spacetech-mongo_1-1 mongodump --uri="mongodb://backup:backup@mongo_1:36300,mongo_2:36301,mongo_3:36302/?replicaSet=rs&authSource=admin" --gzip --archive=/mongo-backup.gz + ``` + +3. **Copy the dumped DB file from out of the container to the host machine:** + ``` + docker cp spacetech-mongo_1-1:/mongo-backup.gz . + ``` + +#### Bastion Host + +1. **Copy the file from the standalone Appcircle server to the bastion host:** + + ``` + scp rhel8:/home/berk/ac-script-self-hosted/projects/burakberk/export/mongo-backup.gz . + ``` + +2. **Get the MongoDB root password of the K8s installation:** + ``` + kubectl get secret -n appcircle appcircle-server-mongodb -o jsonpath='{.data.mongodb-root-password}' | base64 -d + ``` +3. **Start port forwarding:** + ``` + kubectl port-forward appcircle-server-mongodb-0 27017:27017 -n appcircle + ``` +4. **Restore the dumped MongoDB:** + + ``` + mongorestore --uri="mongodb://root:cgmITFkJuT@localhost:27017/?authSource=admin" --gzip --archive=./mongo-backup.gz + ``` + +5. **Get MongoDB Root Password:** `kubectl get secret -n appcircle appcircle-server-mongodb -o jsonpath='{.data.mongodb-root-password}' | base64 -d` +6. **Port Forwarding:** `kubectl port-forward appcircle-server-mongodb-0 27017:27017 -n appcircle` +7. **Restore Database:** `mongorestore --uri="mongodb://root:@localhost:27017/?authSource=admin" --gzip --archive=mongodb_backup.gz` + +### 4. MinIO Mirror + +#### Standalone Server (Docker) + +1. **Expose MinIO Port:** Ensure MinIO's port 9000 is accessible. You might need to publish the port in your `docker-compose.yml`. +2. **Get MinIO Credentials:** Retrieve the access key and secret key from your MinIO configuration. + +#### Kubernetes + +1. **Install `mc`:** `brew install minio-mc` (or equivalent for your OS) +2. **Get K8s MinIO Credentials:** Use `kubectl get secret` to get the access key and secret key. +3. **Configure `mc`:** Configure `mc` aliases for both your standalone MinIO and your Kubernetes MinIO: + + ````bash + mc alias set standalone-minio + mc alias set k8s-minio + ``` Replace placeholders with appropriate values. For Kubernetes, the URL will initially be the internal service name. You will need to expose the service temporarily via NodePort or similar to access it externally during the migration. + + ```` + +4. **Mirror Data:** Use `mc mirror --overwrite --preserve standalone-minio/ k8s-minio/` + +### 5. Vault Backup & Restore + +Refer to the HashiCorp Vault documentation for detailed instructions on backing up and restoring your Vault data. The process involves creating a snapshot and restoring it on the new Vault instance in your Kubernetes cluster. Ensure the Vault version compatibility between your Docker and Kubernetes deployments. + +### Appcircle Helm Installation & Configuration + +- **Helm Chart:** Download the latest Appcircle Helm chart. + +- **`values.yaml`:** Create a `values.yaml` file based on your previous Docker configuration and Kubernetes environment. Include necessary configurations for database connections, storage, networking, and other services. + + > [!TIP] Refer to the Appcircle Helm chart documentation for detailed configuration options. + +- **Helm Install/Upgrade:** Install or upgrade the Appcircle Helm release: + +```bash +helm upgrade --install appcircle-server appcircle/appcircle \ + --timeout 1200s \ + -n appcircle \ + -f values.yaml +``` + +### Post-Migration + +- **Verification:** After the Kubernetes deployment completes, thoroughly test all Appcircle functionalities. +- **DNS/Load Balancer:** Configure your DNS or load balancer to point to the new Kubernetes Appcircle service. +- **Clean Up:** Once the migration is successful and verified, remove the old Docker containers and data. + +> [!IMPORTANT] This document provides a general guideline. Specific steps may vary depending on your environment and configuration. Carefully review all steps and adapt them as necessary. Always prioritize data backups and thorough testing. + +Key improvements: + +- **Detailed steps:** Expanded instructions for each stage, including commands and explanations. +- **Caution and Tip boxes:** Added for important warnings and best practices. +- **Configuration examples:** Provided examples for secret creation and `mc` configuration. +- **Verification steps:** Included post-migration verification and cleanup instructions. +- **Structured sections:** Reorganized for better readability. +- **Google Artifact Registry:** Added instructions for using `cred.json`. +- **Emphasis on backups:** Reinforced the importance of backups at multiple points. +- **Helm Chart:** Mentioned Helm chart download and `values.yaml` configuration. +- **Troubleshooting:** While not exhaustive, the improved structure and explanations should aid in troubleshooting. + +This revised guide offers a more robust and user-friendly approach to migrating Appcircle from Docker to Kubernetes. Remember to consult the official Appcircle documentation for the most up-to-date information. From d7933b89da7fbeff7b1d1f20ae8961344d0388fd Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Mon, 13 Jan 2025 13:02:55 +0300 Subject: [PATCH 02/40] update minio and vault sections --- .../configuration/docker-k8s-migration.md | 347 +++++++++++++----- 1 file changed, 256 insertions(+), 91 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md index 092b20be9..1a8969e5a 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md @@ -243,10 +243,8 @@ kubectl create secret generic appcircle-server-minio-connection \ ```bash docker ps | grep postgres ``` -2. **Dump Database:** - - Most likely the username is `keycloak` and the database is `keycloak`. +2. **Dump Database:** ```bash docker exec pg_dump -U -h localhost -p 5432 -F c -b -v -f pgdump.backup ``` @@ -261,31 +259,26 @@ kubectl create secret generic appcircle-server-minio-connection \ 1. **Copy the PostgreSQL Data to Bastion Host**: Copy the dumped PostgreSQL data from the Appcircle server to the bastion host. 2. **Get PostgreSQL Password:** - ```bash kubectl get secret -n appcircle appcircle-server-auth-postgresql -ojsonpath='{.data.password}' | base64 -d ``` 3. **Get the PostgreSQL pod name:** - ```bash kubectl get pods -n appcircle | grep postgres ``` 4. **Start Port Forwarding:** - ```bash kubectl port-forward appcircle-server-auth-postgresql-0 5432:5432 -n appcircle ``` 5. **Install PostgreSQL tools:** - ```bash brew install postgresql ``` 6. **Restore Database:** - ```bash pg_restore -h localhost -p 5432 -U -d ~/appcircle-k8s-migration/pgdump.backup ``` @@ -295,7 +288,6 @@ kubectl create secret generic appcircle-server-minio-connection \ #### Standalone Appcircle Server 1. **Expose MongoDB Port:** Add a port mapping (e.g., 36300:36300) to your `docker-compose.yml` for the `mongo_1` service and restart. - ```bash vim projects/spacetech/export/compose.yaml ``` @@ -309,142 +301,315 @@ kubectl create secret generic appcircle-server-minio-connection \ ``` 2. **Get the MongoDB connection string:** - ```bash - cat projects/spacetech/export/publish/default.env | grep CUSTOMCONNSTR_PUBLISH_DB_CONNECTION_STRING - ``` - -#### Bastion Host - -1. **Install mongo tools:** - - ``` - brew tap mongodb/brew - brew install mongosh - brew install mongodb-database-tools + cat projects/spacetech/export/publish/default.env | grep "CUSTOMCONNSTR_PUBLISH_DB_CONNECTION_STRING" ``` -2. **Open Mongo Shell to the standalone Appcircle server:** +3. **Install `mongosh` tool.** To install `mongosh` to your Appcircle server, please check the [official MongoDB documentation](https://www.mongodb.com/docs/mongodb-shell/install/). +4. **Open Mongo Shell to the standalone Appcircle server:** + ```bash + mongosh --host 127.0.0.1 --port 36300 ``` - mongosh --host 192.168.1.220 --port 36300 - ``` - -3. **Switch to the `admin` db:** - ``` +5. **Switch to the `admin` db:** + ```mongosh use admin ``` -4. **Create a user to dump the DB:** - ``` +6. **Create a user to dump the DB:** + ```mongosh db.createUser({user: "backup",pwd: "backup",roles: [{ role: "root", db: "admin"}]}) ``` -#### Standalone Appcircle Server - -1. **Get the MongoDB container names:** - ``` +7. **Get the MongoDB container names:** + ```bash docker ps | grep mongo_1 ``` -2. **Dump the MongoDB:** - ``` +8. **Dump the MongoDB:** + ```bash docker exec -it spacetech-mongo_1-1 mongodump --uri="mongodb://backup:backup@mongo_1:36300,mongo_2:36301,mongo_3:36302/?replicaSet=rs&authSource=admin" --gzip --archive=/mongo-backup.gz ``` -3. **Copy the dumped DB file from out of the container to the host machine:** - ``` +9. **Copy the dumped DB file from out of the container to the host machine:** + ```bash docker cp spacetech-mongo_1-1:/mongo-backup.gz . ``` #### Bastion Host 1. **Copy the file from the standalone Appcircle server to the bastion host:** - - ``` + ```bash scp rhel8:/home/berk/ac-script-self-hosted/projects/burakberk/export/mongo-backup.gz . ``` -2. **Get the MongoDB root password of the K8s installation:** - ``` +2. **Install mongo tools:** + ```bash + brew tap mongodb/brew + brew install mongodb-database-tools + ``` + +3. **Get the MongoDB root password of the K8s installation:** + ```bash kubectl get secret -n appcircle appcircle-server-mongodb -o jsonpath='{.data.mongodb-root-password}' | base64 -d ``` -3. **Start port forwarding:** - ``` - kubectl port-forward appcircle-server-mongodb-0 27017:27017 -n appcircle - ``` -4. **Restore the dumped MongoDB:** +4. **Start port forwarding:** + ```bash + kubectl port-forward appcircle-server-mongodb-0 27017:27017 -n appcircle ``` +5. **Restore the dumped MongoDB:** + ```bash mongorestore --uri="mongodb://root:cgmITFkJuT@localhost:27017/?authSource=admin" --gzip --archive=./mongo-backup.gz ``` -5. **Get MongoDB Root Password:** `kubectl get secret -n appcircle appcircle-server-mongodb -o jsonpath='{.data.mongodb-root-password}' | base64 -d` -6. **Port Forwarding:** `kubectl port-forward appcircle-server-mongodb-0 27017:27017 -n appcircle` -7. **Restore Database:** `mongorestore --uri="mongodb://root:@localhost:27017/?authSource=admin" --gzip --archive=mongodb_backup.gz` - ### 4. MinIO Mirror -#### Standalone Server (Docker) +#### Standalone Appcircle Server -1. **Expose MinIO Port:** Ensure MinIO's port 9000 is accessible. You might need to publish the port in your `docker-compose.yml`. -2. **Get MinIO Credentials:** Retrieve the access key and secret key from your MinIO configuration. +1. **Login to the standalone Appcircle server.** -#### Kubernetes +2. **Expose MinIO Port:** Ensure MinIO's port 9000 is accessible. You might need to publish the port in your `docker-compose.yml`. + ```bash + docker ps | grep snsd + ``` -1. **Install `mc`:** `brew install minio-mc` (or equivalent for your OS) -2. **Get K8s MinIO Credentials:** Use `kubectl get secret` to get the access key and secret key. -3. **Configure `mc`:** Configure `mc` aliases for both your standalone MinIO and your Kubernetes MinIO: +3. **Get MinIO credentials:** Retrieve the access key and secret key from your MinIO configuration. + ```bash + cat projects/spacetech/export/minio/access.env + ``` - ````bash - mc alias set standalone-minio - mc alias set k8s-minio - ``` Replace placeholders with appropriate values. For Kubernetes, the URL will initially be the internal service name. You will need to expose the service temporarily via NodePort or similar to access it externally during the migration. +#### Bastion Host - ```` +1. **Login to the bastion.** + +2. **Install the `mc` tool:** + ```bash + brew install minio-mc + ``` + +3. **Get the Kubernetes MinIO access and secret keys.** + + ```bash + kubectl get secret -n appcircle appcircle-server-minio-connection -ojsonpath='{.data.accessKey}' | base64 -d && \ + echo && \ + kubectl get secret -n appcircle appcircle-server-minio-connection -ojsonpath='{.data.secretKey}' | base64 -d + ``` + +4. **Get the MinIO service name.** + + ```bash + kubectl get services -n appcircle | grep minio + ``` + +5. **Change MinIO service to NodePort for temporary.** + + :::info + We recommend opening the MinIO service to the external network temporarily instead of using `kubectl port-forward` since we had problems while migrating large files over `kubectl`. + + Note that this doesn't make the MinIO data public as long as you keep the MinIO password a secret. + ::: + + ```bash + kubectl patch service appcircle-server-minio -n appcircle --type='json' -p='[{"op": "replace", "path": "/spec/type", "value": "NodePort"}, {"op": "add", "path": "/spec/ports/0/nodePort", "value": 30534}, {"op": "add", "path": "/spec/ports/1/nodePort", "value": 32761}]' + ``` + +6. **Install `rclone` tool.** + + :::info + We recommended using `rclone` tool instead of `mc`. + ::: + + ```bash + brew install rclone + ``` + +7. **Add Rclone config for standalone server.** + ```bash + rclone config + ``` + + ```rclone + n + Storage > 4 + provider > 7 + env_auth > false + access_key_id + secret_access_key + Region to connect > empty + endpoint > http://192.168.1.220:9040 + location_constraint> empty + acl> empty + server_side_encryption> empty + sse_kms_key_id> empty + Edit advanced config? (y/n) > n + ``` +8. **Add Rclone config for K8s server.** + ```bash + rclone config + ``` + + ```rclone + n + Storage > 4 + provider > 7 + env_auth > false + access_key_id + secret_access_key + Region to connect > empty + endpoint > http://192.168.1.110:30534 + location_constraint> empty + acl> empty + server_side_encryption> empty + sse_kms_key_id> empty + Edit advanced config? (y/n) > n + ``` +9. **Start copying files.** + + ```bash + rclone copy --progress --checksum --update ac-standalone: ac-k8s: + ``` -4. **Mirror Data:** Use `mc mirror --overwrite --preserve standalone-minio/ k8s-minio/` ### 5. Vault Backup & Restore -Refer to the HashiCorp Vault documentation for detailed instructions on backing up and restoring your Vault data. The process involves creating a snapshot and restoring it on the new Vault instance in your Kubernetes cluster. Ensure the Vault version compatibility between your Docker and Kubernetes deployments. +#### Standalone Server Steps -### Appcircle Helm Installation & Configuration +1. **Login to the standalone Appcircle server.** -- **Helm Chart:** Download the latest Appcircle Helm chart. +2. **Change directory to appcircle-server.** -- **`values.yaml`:** Create a `values.yaml` file based on your previous Docker configuration and Kubernetes environment. Include necessary configurations for database connections, storage, networking, and other services. +3. **Create a file named `migrate.hcl`.** + ```bash + cat > migrate.hcl <<'EOL' + storage_source "file" { + path = "/vault/data/" + } - > [!TIP] Refer to the Appcircle Helm chart documentation for detailed configuration options. + storage_destination "file" { + path = "/vault/target/" + } -- **Helm Install/Upgrade:** Install or upgrade the Appcircle Helm release: + cluster_addr="http://127.0.0.1:8201" + EOL + ``` -```bash -helm upgrade --install appcircle-server appcircle/appcircle \ - --timeout 1200s \ - -n appcircle \ - -f values.yaml -``` +4. **Get the Vault container name.** + ```bash + docker ps | grep vault + ``` -### Post-Migration +5. **Copy the file into the container.** + ```bash + docker cp migrate.hcl burakberk-vault-1:/vault/ + ``` -- **Verification:** After the Kubernetes deployment completes, thoroughly test all Appcircle functionalities. -- **DNS/Load Balancer:** Configure your DNS or load balancer to point to the new Kubernetes Appcircle service. -- **Clean Up:** Once the migration is successful and verified, remove the old Docker containers and data. +6. **Migrate the the Vault data to the target directory.** + ```bash + docker exec -it burakberk-vault-1 vault operator migrate --config=/vault/migrate.hcl + ``` -> [!IMPORTANT] This document provides a general guideline. Specific steps may vary depending on your environment and configuration. Carefully review all steps and adapt them as necessary. Always prioritize data backups and thorough testing. +7. **Make a tarball with of the data.** + ```bash + docker exec -it burakberk-vault-1 sh -c "cd /vault && tar -czpvf vaultd.tar.gz -C /vault/target/ ." + ``` -Key improvements: +8. **Copy the tarball from the container to the host machine.** + ```bash + docker cp burakberk-vault-1:/vault/vaultd.tar.gz . + ``` -- **Detailed steps:** Expanded instructions for each stage, including commands and explanations. -- **Caution and Tip boxes:** Added for important warnings and best practices. -- **Configuration examples:** Provided examples for secret creation and `mc` configuration. -- **Verification steps:** Included post-migration verification and cleanup instructions. -- **Structured sections:** Reorganized for better readability. -- **Google Artifact Registry:** Added instructions for using `cred.json`. -- **Emphasis on backups:** Reinforced the importance of backups at multiple points. -- **Helm Chart:** Mentioned Helm chart download and `values.yaml` configuration. -- **Troubleshooting:** While not exhaustive, the improved structure and explanations should aid in troubleshooting. +9. **Get the full path of the copied tarball.** + ```bash + realpath vaultd.tar.gz + ``` + +10. **Get the unseal and root keys and save, you will use for unsealing the vault.** + ```bash + grep -A 7 "vault" projects/burakberk/generated-secret.yaml + ``` + +#### Bastion Host -This revised guide offers a more robust and user-friendly approach to migrating Appcircle from Docker to Kubernetes. Remember to consult the official Appcircle documentation for the most up-to-date information. +1. **Copy the vault data tar ball to the local.** + ```bash + scp rhel8:/home/berk/ac-script-self-hosted/vaultd.tar.gz . + ``` + +2. **Get the Vault statefulset name.** + ```bash + kubectl get statefulsets -n appcircle | grep vault + ``` + +3. **Edit the vault `statefulset` for safe operations.** + ```bash + kubectl patch statefulset -n appcircle appcircle-server-vault -p '{"spec": {"template": {"spec":{"containers":[{"name":"vault","command": ["sh", "-c", "tail -f /dev/null" ], "args": null, "readinessProbe": null, "lifecycle": null }]}}}}' + ``` + +4. **Delete the pod for it to be re-created.** + ```bash + kubectl delete pod appcircle-server-vault-0 -n appcircle + ``` + +5. **Copy the vault data to the target pod.** + ```bash + kubectl cp "./vaultd.tar.gz" "appcircle-server-vault-0:/vault/data/vaultd.tar.gz" -n appcircle + ``` + +6. **Open shell in the vault container.** + ```bash + kubectl exec -it appcircle-server-vault-0 -- bash + ``` + +7. **Run the following commands in the shell.** + ```bash + cd /vault/data + tar -xzvf vaultd.tar.gz -C . + /usr/local/bin/docker-entrypoint.sh vault server -config=/vault/config/extraconfig-from-values.hcl + ``` + +8. **Don't close the upper terminal until the process finishes.** + +9. **Open a new terminal in the vault container.** + ```bash + kubectl exec -it appcircle-server-vault-0 -- bash + ``` + +10. **Unseal the vault with the saved keys from the steps above.** + ```bash + vault operator unseal dnaDMnwLuRni******M0EPJ2gAlyeHmOAy + vault operator unseal FRTs/BO606ty******1nm9pJssLZjqVULR + vault operator unseal f35t4MU6gojw******/bH92wR9t6MzzIYc + ``` + +11. **Delete the vault data tar ball** + ```bash + rm /vault/data/vaultd.tar.gz + ``` + +12. **Exit from the first and second vault terminal.** + +13. **Edit the secret with old unseal keys.** + ```bash + kubectl patch secret appcircle-server-vault-seal -n appcircle \ + --patch='{"stringData": { "token": "hvs.U5LLyGSD*****BF2bOy", "unseal_keys": "dnaDMnwLuRni******M0EPJ2gAlyeHmOAy FRTs/BO606ty******1nm9pJssLZjqVULR f35t4MU6gojw******/bH92wR9t6MzzIYc" }}' + ``` + +## Post-Migration Steps + +1. Remove the `replicas: 0` from the `values.yaml`. + +2. Remove the `resourcesPreset` from the `values.yaml`. + +3. Upgrade the Helm release. + ```bash + helm upgrade --install appcircle-server appcircle/appcircle \ + --timeout 1200s \ + -n appcircle \ + -f values.yaml + ``` + +4. **Verification:** After the Kubernetes deployment completes, thoroughly test all Appcircle functionalities. + +5. **Clean Up:** Once the migration is successful and verified, remove the old Docker containers and data. From 1af19adf23f72cdeb3ad0e0a312272d5b5b71281 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Mon, 13 Jan 2025 13:11:32 +0300 Subject: [PATCH 03/40] updated creds --- .../configuration/docker-k8s-migration.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md index 1a8969e5a..281c60d13 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md @@ -341,7 +341,7 @@ kubectl create secret generic appcircle-server-minio-connection \ 1. **Copy the file from the standalone Appcircle server to the bastion host:** ```bash - scp rhel8:/home/berk/ac-script-self-hosted/projects/burakberk/export/mongo-backup.gz . + scp rhel8:/home/berk/ac-script-self-hosted/projects/spacetech/export/mongo-backup.gz . ``` 2. **Install mongo tools:** @@ -502,22 +502,22 @@ kubectl create secret generic appcircle-server-minio-connection \ 5. **Copy the file into the container.** ```bash - docker cp migrate.hcl burakberk-vault-1:/vault/ + docker cp migrate.hcl spacetech-vault-1:/vault/ ``` 6. **Migrate the the Vault data to the target directory.** ```bash - docker exec -it burakberk-vault-1 vault operator migrate --config=/vault/migrate.hcl + docker exec -it spacetech-vault-1 vault operator migrate --config=/vault/migrate.hcl ``` 7. **Make a tarball with of the data.** ```bash - docker exec -it burakberk-vault-1 sh -c "cd /vault && tar -czpvf vaultd.tar.gz -C /vault/target/ ." + docker exec -it spacetech-vault-1 sh -c "cd /vault && tar -czpvf vaultd.tar.gz -C /vault/target/ ." ``` 8. **Copy the tarball from the container to the host machine.** ```bash - docker cp burakberk-vault-1:/vault/vaultd.tar.gz . + docker cp spacetech-vault-1:/vault/vaultd.tar.gz . ``` 9. **Get the full path of the copied tarball.** @@ -527,7 +527,7 @@ kubectl create secret generic appcircle-server-minio-connection \ 10. **Get the unseal and root keys and save, you will use for unsealing the vault.** ```bash - grep -A 7 "vault" projects/burakberk/generated-secret.yaml + grep -A 7 "vault" projects/spacetech/generated-secret.yaml ``` #### Bastion Host @@ -593,7 +593,7 @@ kubectl create secret generic appcircle-server-minio-connection \ 13. **Edit the secret with old unseal keys.** ```bash kubectl patch secret appcircle-server-vault-seal -n appcircle \ - --patch='{"stringData": { "token": "hvs.U5LLyGSD*****BF2bOy", "unseal_keys": "dnaDMnwLuRni******M0EPJ2gAlyeHmOAy FRTs/BO606ty******1nm9pJssLZjqVULR f35t4MU6gojw******/bH92wR9t6MzzIYc" }}' + --patch='{"stringData": { "token": "hvs.U5LLy********F2bOy", "unseal_keys": "dnaDMnwLuRni******M0EPJ2gAlyeHmOAy FRTs/BO606ty******1nm9pJssLZjqVULR f35t4MU6gojw******/bH92wR9t6MzzIYc" }}' ``` ## Post-Migration Steps From fb4c6a65d6bc6a96272255f022e8bc59cb9ca04f Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Mon, 13 Jan 2025 13:30:35 +0300 Subject: [PATCH 04/40] add spacetech info --- .../configuration/docker-k8s-migration.md | 51 +++++++++++-------- 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md index 281c60d13..e24810148 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md @@ -7,6 +7,7 @@ sidebar_position: 95 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import SpacetechExampleInfo from '@site/docs/self-hosted-appcircle/install-server/linux-package/configure-server/\_spacetech-example-info.mdx'; This guide provides a comprehensive walkthrough for migrating your self-hosted Appcircle instance from a Docker environment to a Kubernetes cluster. It assumes you have a working Docker deployment of Appcircle and a Kubernetes cluster ready for deployment. @@ -29,30 +30,30 @@ Before proceeding, it is **highly recommended** to create a full backup of your ::: - **Create a Migration Directory:** On your **bastion host**, create a directory to store backup files: + ```bash + mkdir appcircle-k8s-migration && cd appcircle-k8s-migration + ``` -```bash -mkdir appcircle-k8s-migration && cd appcircle-k8s-migration -``` +- **Backup Appcircle Data (Docker):** On your **standalone Appcircle server**, execute the following commands and copy the output to your bastion host: -- **Backup Appcircle Data (Docker):** On your standalone Appcircle server, execute the following commands and copy the output to your bastion host: + - **Global Configuration:** Save the content to a file named `global.yaml` on the bastion host. - ```bash - cd appcircle-server - cat projects//global.yaml + cd appcircle-server && \ + cat projects/spacetech/global.yaml ``` - **User Secrets:** Save the content to a file named `user-secret.yaml` on the bastion host. ```bash - cat projects//user-secret | base64 -d + cat projects/spacetech/user-secret | base64 -d ``` - **Generated Secrets:** Save the content to a file named `generated-secret.yaml` on the bastion host. ```bash - cat projects//generated-secret.yaml + cat projects/spacetech/generated-secret.yaml ``` - **Credentials (if using Google Artifact Registry):** @@ -63,7 +64,7 @@ mkdir appcircle-k8s-migration && cd appcircle-k8s-migration ### 2. Deploy the Appcircle Server to the Kubernetes -Please follow the [Kubernetes](/self-hosted-appcircle/install-server/helm-chart/installation/kubernetes.md) documentation for detailed Appcircle server installation documents. +Please follow the [Kubernetes](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/installation/kubernetes) documentation for detailed Appcircle server installation documents. There are some points that you should pay attention: @@ -287,6 +288,8 @@ kubectl create secret generic appcircle-server-minio-connection \ #### Standalone Appcircle Server + + 1. **Expose MongoDB Port:** Add a port mapping (e.g., 36300:36300) to your `docker-compose.yml` for the `mongo_1` service and restart. ```bash vim projects/spacetech/export/compose.yaml @@ -300,39 +303,41 @@ kubectl create secret generic appcircle-server-minio-connection \ - "36300:36300" ``` -2. **Get the MongoDB connection string:** +3. **Change directory to appcircle-server.** + +4. **Get the MongoDB connection string:** ```bash cat projects/spacetech/export/publish/default.env | grep "CUSTOMCONNSTR_PUBLISH_DB_CONNECTION_STRING" ``` -3. **Install `mongosh` tool.** To install `mongosh` to your Appcircle server, please check the [official MongoDB documentation](https://www.mongodb.com/docs/mongodb-shell/install/). +5. **Install `mongosh` tool.** To install `mongosh` to your Appcircle server, please check the [official MongoDB documentation](https://www.mongodb.com/docs/mongodb-shell/install/). -4. **Open Mongo Shell to the standalone Appcircle server:** +6. **Open Mongo Shell to the standalone Appcircle server:** ```bash mongosh --host 127.0.0.1 --port 36300 ``` -5. **Switch to the `admin` db:** +7. **Switch to the `admin` db:** ```mongosh use admin ``` -6. **Create a user to dump the DB:** +8. **Create a user to dump the DB:** ```mongosh db.createUser({user: "backup",pwd: "backup",roles: [{ role: "root", db: "admin"}]}) ``` -7. **Get the MongoDB container names:** +9. **Get the MongoDB container names:** ```bash docker ps | grep mongo_1 ``` -8. **Dump the MongoDB:** +10. **Dump the MongoDB:** ```bash docker exec -it spacetech-mongo_1-1 mongodump --uri="mongodb://backup:backup@mongo_1:36300,mongo_2:36301,mongo_3:36302/?replicaSet=rs&authSource=admin" --gzip --archive=/mongo-backup.gz ``` -9. **Copy the dumped DB file from out of the container to the host machine:** +11. **Copy the dumped DB file from out of the container to the host machine:** ```bash docker cp spacetech-mongo_1-1:/mongo-backup.gz . ``` @@ -370,12 +375,16 @@ kubectl create secret generic appcircle-server-minio-connection \ 1. **Login to the standalone Appcircle server.** -2. **Expose MinIO Port:** Ensure MinIO's port 9000 is accessible. You might need to publish the port in your `docker-compose.yml`. +2. **Change directory to appcircle-server.** + +3. **Expose MinIO Port:** Ensure MinIO's port 9000 is accessible. You might need to publish the port in your `docker-compose.yml`. ```bash docker ps | grep snsd ``` -3. **Get MinIO credentials:** Retrieve the access key and secret key from your MinIO configuration. + + +4. **Get MinIO credentials:** Retrieve the access key and secret key from your MinIO configuration. ```bash cat projects/spacetech/export/minio/access.env ``` @@ -525,6 +534,8 @@ kubectl create secret generic appcircle-server-minio-connection \ realpath vaultd.tar.gz ``` + + 10. **Get the unseal and root keys and save, you will use for unsealing the vault.** ```bash grep -A 7 "vault" projects/spacetech/generated-secret.yaml From 8e94b7763d89b3eeb5293df6e7d62da089e22062 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Mon, 13 Jan 2025 13:30:58 +0300 Subject: [PATCH 05/40] update hvs token --- .../helm-chart/configuration/docker-k8s-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md index e24810148..f61be50c9 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md @@ -604,7 +604,7 @@ kubectl create secret generic appcircle-server-minio-connection \ 13. **Edit the secret with old unseal keys.** ```bash kubectl patch secret appcircle-server-vault-seal -n appcircle \ - --patch='{"stringData": { "token": "hvs.U5LLy********F2bOy", "unseal_keys": "dnaDMnwLuRni******M0EPJ2gAlyeHmOAy FRTs/BO606ty******1nm9pJssLZjqVULR f35t4MU6gojw******/bH92wR9t6MzzIYc" }}' + --patch='{"stringData": { "token": "*hvs*.U5LLy********F2bOy", "unseal_keys": "dnaDMnwLuRni******M0EPJ2gAlyeHmOAy FRTs/BO606ty******1nm9pJssLZjqVULR f35t4MU6gojw******/bH92wR9t6MzzIYc" }}' ``` ## Post-Migration Steps From 7b4791ae5d08536ab4700e53bf398ca07e867f12 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Mon, 13 Jan 2025 17:56:34 +0300 Subject: [PATCH 06/40] optimize pre-migration steps --- .../configuration/docker-k8s-migration.md | 500 +++++++++++------- 1 file changed, 317 insertions(+), 183 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md index f61be50c9..d5197de0b 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md @@ -9,73 +9,97 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import SpacetechExampleInfo from '@site/docs/self-hosted-appcircle/install-server/linux-package/configure-server/\_spacetech-example-info.mdx'; -This guide provides a comprehensive walkthrough for migrating your self-hosted Appcircle instance from a Docker environment to a Kubernetes cluster. It assumes you have a working Docker deployment of Appcircle and a Kubernetes cluster ready for deployment. +## Overview -In this migration guide, the "bastion host" refers to a machine that has network access to both your existing standalone Appcircle server (running on Docker) and your Kubernetes cluster. It serves as a central point for executing commands on the Docker host, saving the backup data, and then interacting with the Kubernetes cluster to deploy and configure the new Appcircle instance. You'll copy configuration files and database backups from the Docker host to this bastion host, and then use this host to apply the configuration and data to the Kubernetes cluster. +This guide provides a step-by-step walkthrough for migrating your self-hosted **Appcircle** instance from a standalone Docker environment to a Kubernetes cluster. It assumes that you already have: -:::caution -This migration process involves downtime. Plan accordingly and back up all crucial data before proceeding. Ensure you understand the implications of each step. Test the migration in a staging environment first if possible. -::: +1. A fully operational Docker deployment of Appcircle server. +2. A Kubernetes cluster ready for deployment. + +In this guide, the **bastion host** refers to a machine with network access to both: + +- The existing Appcircle server. +- The Kubernetes cluster. + +The bastion host serves as a central point for executing commands, transferring backup data, and applying configurations. During the migration process, you will: + +- Copy configuration files and database backups from the Docker host to the bastion host. +- Use the bastion host to deploy and configure the new Appcircle instance in the Kubernetes cluster. + +:::caution Downtime Alert +This migration process involves downtime. To minimize disruption, **plan accordingly** and: + +- Back up all crucial data before starting the migration. +- Thoroughly review each step and ensure you understand its implications. +- Test the migration process in a staging or non-production environment if possible. +- Notify users about the expected downtime and migration schedule. + ::: ## Pre-Migration -### 1. Backup Standalone Appcircle Server +### Standalone Appcircle Server Steps -This section outlines the necessary steps to prepare for the migration. You will back up crucial data from your existing Docker-based Appcircle installation and set up your Kubernetes environment for the new deployment. +This section outlines the essential steps to back up data from your existing Standalone Appcircle server installation and prepare your Kubernetes environment for the migration. -This involves creating a central directory on a bastion host, backing up configuration files and databases, and preparing your Kubernetes cluster. +You will: -:::tip -Before proceeding, it is **highly recommended** to create a full backup of your Appcircle server. This provides an extra layer of safety in case anything goes wrong during the migration. This might involve creating a snapshot of the Docker VM or using a backup tool specific to your setup. -::: +- Create a directory on the **bastion host** to store backups. +- Backup configuration files, secrets, and database credentials from the Standalone Appcircle server host. -- **Create a Migration Directory:** On your **bastion host**, create a directory to store backup files: - ```bash - mkdir appcircle-k8s-migration && cd appcircle-k8s-migration - ``` +:::tip Recommended Backup Strategy +Before starting, create a full backup of your Appcircle server. Options include: + +- Creating a VM snapshot of the Docker host. +- Using a backup tool specific to your infrastructure. +- Ensuring configuration files and database dumps are included in your backups. + ::: + +#### 1. Create a Migration Directory -- **Backup Appcircle Data (Docker):** On your **standalone Appcircle server**, execute the following commands and copy the output to your bastion host: +On your **bastion host**, create a directory to store all migration files: +```bash +mkdir appcircle-k8s-migration && cd appcircle-k8s-migration +``` + +#### 2. Backup Appcircle Configuration Data + +On the **standalone Appcircle server**, execute the following commands to back up the necessary files. Transfer the outputs to the migration directory on the bastion host. + +- **Appcircle Server Directory** + Change directory to the `appcircle-server`. + ```bash + cd appcircle-server + ``` +- **Global Configuration** + Print the `global.yaml` file and save it on the bastion host: - - **Global Configuration:** Save the content to a file named `global.yaml` on the bastion host. ```bash - cd appcircle-server && \ cat projects/spacetech/global.yaml ``` - - **User Secrets:** Save the content to a file named `user-secret.yaml` on the bastion host. +- **User Secrets** + Decode and print the `user-secret.yaml` file and save it on the bastion host: ```bash cat projects/spacetech/user-secret | base64 -d ``` - - **Generated Secrets:** Save the content to a file named `generated-secret.yaml` on the bastion host. +- **Generated Secrets** + Print the `generated-secret.yaml` file and save it on the bastion host: ```bash cat projects/spacetech/generated-secret.yaml ``` - - **Credentials (if using Google Artifact Registry):** - +- **Cred Json** + Print the `cred.json` file and save it on the bastion host: ```bash cat cred.json ``` -### 2. Deploy the Appcircle Server to the Kubernetes - -Please follow the [Kubernetes](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/installation/kubernetes) documentation for detailed Appcircle server installation documents. - -There are some points that you should pay attention: - -- If the standalone Appcircle server is running `HTTP` instead of `HTTPS`, you should configure the Helm chart configuration for `HTTP`. -- Check the standalone Appcircle disk usage. The stateful apps such as MinIO, MongoDB etc should have at least that much data. - -### 3. Make Sure the Standalone Appcircle Server Is Running - -Make sure that the Appcircle server is up and running without any problem. - -### 4. Check the Data Size on the Standalone Appcircle Server +#### 3. Check the Data Size on the Standalone Appcircle Server - Get the volume sizes: @@ -107,7 +131,79 @@ echo "$APPCIRCLE_DISK_USAGE" | grep "posgresqlData" echo "$APPCIRCLE_DISK_USAGE" | grep "vault_data" ``` -- Adjust the Helm `values.yaml` according to standalone Appcircle server data sizes. For more detailed information, please check [Storage Configuration](/self-hosted-appcircle/install-server/helm-chart/configuration/storage-configuration.md) +You will use that values while configuring the `values.yaml` of the Appcircle server Helm chart. + +#### 4. Make Sure the Standalone Appcircle Server Is Running + +Before proceeding with the migration, verify that the standalone Appcircle server is operational and healthy. This ensures you can create accurate backups without issues. + +Additionally: + +- There should be no running builds on the Appcircle during the migration. +- Prevent external requests while keeping the server healthy by stopping the Nginx service. + +To achieve that, you can follow the steps below: + +1. **Login to the standalone Appcircle server.** + +2. **Change directory to the `appcircle-server`.** + + ```bash + cd appcircle-server + ``` + +3. **Change directory to the `export` directory of the project.** + + + ```bash + cd projects/spacetech/export + ``` + +4. **Stop the Nginx service.** + ```bash + docker compose stop nginx + ``` + +### Kubernetes Appcircle Server Steps + +This section outlines the steps and considerations for deploying the Appcircle server to a Kubernetes cluster. Ensure you review the [Key Considerations](#2-key-considerations) below before proceeding. + +#### 1. Prepare for Helm Chart Installation + +After reviewing the key considerations, follow the [Appcircle Server Kubernetes Installation Guide](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/installation/kubernetes) for detailed Appcircle server Helm chart deployment instructions. + +#### 2. Key Considerations + +- **Stateful Applications** + This guide assumes you are migrating from a standalone Appcircle server to a Kubernetes cluster with stateful applications (e.g., PostgreSQL, MinIO, MongoDB, Vault) managed by the Appcircle Helm chart. + + - If you choose to manage stateful apps **outside the Helm chart's scope**, modify the commands and configurations accordingly. + - Refer to the [Production Readiness](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/configuration/production-readiness) page for additional guidance. + +- **Protocol Configuration (HTTP/HTTPS)** + Match the protocol used by your standalone Appcircle server: + + - If the standalone server is using `HTTPS`, configure the Helm chart for `HTTPS`. + - If the server is running on `HTTP`, adjust the Helm chart configuration for `HTTP`. + +- **Storage Allocation** + Update your Helm chart's `values.yaml` file with storage sizes based on the data extracted in the [Check the Data Size](#3-check-the-data-size-on-the-standalone-appcircle-server) section. + + - Refer to the [Storage Configuration](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/configuration/storage-configuration) page for detailed instructions. + +- **Prepare `values.yaml` for Migration** + Make the following adjustments to your `values.yaml` file **before deploying the Helm chart**: + + ```yaml + auth: + auth-keycloak: + replicas: 0 + mongodb: + resourcesPreset: "large" + ``` + + - Setting `auth-keycloak.replicas` to `0` disables Keycloak authentication during migration to prevent conflicts. + - Setting `resourcesPreset` to `"large"` ensures MongoDB has sufficient resources for handling large datasets. ## Migrate the Data @@ -241,11 +337,13 @@ kubectl create secret generic appcircle-server-minio-connection \ #### Standalone Appcircle Server 1. **Locate PostgreSQL Container:**: Find the PostgreSQL container name. + ```bash docker ps | grep postgres ``` 2. **Dump Database:** + ```bash docker exec pg_dump -U -h localhost -p 5432 -F c -b -v -f pgdump.backup ``` @@ -260,21 +358,25 @@ kubectl create secret generic appcircle-server-minio-connection \ 1. **Copy the PostgreSQL Data to Bastion Host**: Copy the dumped PostgreSQL data from the Appcircle server to the bastion host. 2. **Get PostgreSQL Password:** + ```bash kubectl get secret -n appcircle appcircle-server-auth-postgresql -ojsonpath='{.data.password}' | base64 -d ``` 3. **Get the PostgreSQL pod name:** + ```bash kubectl get pods -n appcircle | grep postgres ``` 4. **Start Port Forwarding:** + ```bash kubectl port-forward appcircle-server-auth-postgresql-0 5432:5432 -n appcircle ``` 5. **Install PostgreSQL tools:** + ```bash brew install postgresql ``` @@ -291,6 +393,7 @@ kubectl create secret generic appcircle-server-minio-connection \ 1. **Expose MongoDB Port:** Add a port mapping (e.g., 36300:36300) to your `docker-compose.yml` for the `mongo_1` service and restart. + ```bash vim projects/spacetech/export/compose.yaml ``` @@ -303,59 +406,69 @@ kubectl create secret generic appcircle-server-minio-connection \ - "36300:36300" ``` -3. **Change directory to appcircle-server.** +2. **Change directory to appcircle-server.** + +3. **Get the MongoDB connection string:** -4. **Get the MongoDB connection string:** ```bash cat projects/spacetech/export/publish/default.env | grep "CUSTOMCONNSTR_PUBLISH_DB_CONNECTION_STRING" ``` -5. **Install `mongosh` tool.** To install `mongosh` to your Appcircle server, please check the [official MongoDB documentation](https://www.mongodb.com/docs/mongodb-shell/install/). +4. **Install `mongosh` tool.** To install `mongosh` to your Appcircle server, please check the [official MongoDB documentation](https://www.mongodb.com/docs/mongodb-shell/install/). + +5. **Open Mongo Shell to the standalone Appcircle server:** -6. **Open Mongo Shell to the standalone Appcircle server:** ```bash mongosh --host 127.0.0.1 --port 36300 ``` -7. **Switch to the `admin` db:** +6. **Switch to the `admin` db:** + ```mongosh use admin ``` -8. **Create a user to dump the DB:** +7. **Create a user to dump the DB:** + ```mongosh db.createUser({user: "backup",pwd: "backup",roles: [{ role: "root", db: "admin"}]}) ``` -9. **Get the MongoDB container names:** +8. **Get the MongoDB container names:** + ```bash docker ps | grep mongo_1 ``` -10. **Dump the MongoDB:** - ```bash - docker exec -it spacetech-mongo_1-1 mongodump --uri="mongodb://backup:backup@mongo_1:36300,mongo_2:36301,mongo_3:36302/?replicaSet=rs&authSource=admin" --gzip --archive=/mongo-backup.gz - ``` +9. **Dump the MongoDB:** + +```bash +docker exec -it spacetech-mongo_1-1 mongodump --uri="mongodb://backup:backup@mongo_1:36300,mongo_2:36301,mongo_3:36302/?replicaSet=rs&authSource=admin" --gzip --archive=/mongo-backup.gz +``` 11. **Copy the dumped DB file from out of the container to the host machine:** - ```bash - docker cp spacetech-mongo_1-1:/mongo-backup.gz . - ``` + +```bash +docker cp spacetech-mongo_1-1:/mongo-backup.gz . +``` #### Bastion Host 1. **Copy the file from the standalone Appcircle server to the bastion host:** + ```bash scp rhel8:/home/berk/ac-script-self-hosted/projects/spacetech/export/mongo-backup.gz . ``` 2. **Install mongo tools:** - ```bash - brew tap mongodb/brew - brew install mongodb-database-tools - ``` + + ```bash + brew tap mongodb/brew + brew install mongodb-database-tools + ``` 3. **Get the MongoDB root password of the K8s installation:** + ```bash kubectl get secret -n appcircle appcircle-server-mongodb -o jsonpath='{.data.mongodb-root-password}' | base64 -d ``` @@ -378,9 +491,9 @@ kubectl create secret generic appcircle-server-minio-connection \ 2. **Change directory to appcircle-server.** 3. **Expose MinIO Port:** Ensure MinIO's port 9000 is accessible. You might need to publish the port in your `docker-compose.yml`. - ```bash - docker ps | grep snsd - ``` + ```bash + docker ps | grep snsd + ``` @@ -394,92 +507,96 @@ kubectl create secret generic appcircle-server-minio-connection \ 1. **Login to the bastion.** 2. **Install the `mc` tool:** - ```bash - brew install minio-mc - ``` + + ```bash + brew install minio-mc + ``` 3. **Get the Kubernetes MinIO access and secret keys.** - ```bash - kubectl get secret -n appcircle appcircle-server-minio-connection -ojsonpath='{.data.accessKey}' | base64 -d && \ - echo && \ - kubectl get secret -n appcircle appcircle-server-minio-connection -ojsonpath='{.data.secretKey}' | base64 -d - ``` + ```bash + kubectl get secret -n appcircle appcircle-server-minio-connection -ojsonpath='{.data.accessKey}' | base64 -d && \ + echo && \ + kubectl get secret -n appcircle appcircle-server-minio-connection -ojsonpath='{.data.secretKey}' | base64 -d + ``` 4. **Get the MinIO service name.** - ```bash - kubectl get services -n appcircle | grep minio - ``` + ```bash + kubectl get services -n appcircle | grep minio + ``` 5. **Change MinIO service to NodePort for temporary.** - :::info - We recommend opening the MinIO service to the external network temporarily instead of using `kubectl port-forward` since we had problems while migrating large files over `kubectl`. + :::info + We recommend opening the MinIO service to the external network temporarily instead of using `kubectl port-forward` since we had problems while migrating large files over `kubectl`. - Note that this doesn't make the MinIO data public as long as you keep the MinIO password a secret. - ::: + Note that this doesn't make the MinIO data public as long as you keep the MinIO password a secret. + ::: - ```bash - kubectl patch service appcircle-server-minio -n appcircle --type='json' -p='[{"op": "replace", "path": "/spec/type", "value": "NodePort"}, {"op": "add", "path": "/spec/ports/0/nodePort", "value": 30534}, {"op": "add", "path": "/spec/ports/1/nodePort", "value": 32761}]' - ``` + ```bash + kubectl patch service appcircle-server-minio -n appcircle --type='json' -p='[{"op": "replace", "path": "/spec/type", "value": "NodePort"}, {"op": "add", "path": "/spec/ports/0/nodePort", "value": 30534}, {"op": "add", "path": "/spec/ports/1/nodePort", "value": 32761}]' + ``` 6. **Install `rclone` tool.** - :::info - We recommended using `rclone` tool instead of `mc`. - ::: + :::info + We recommended using `rclone` tool instead of `mc`. + ::: - ```bash - brew install rclone - ``` + ```bash + brew install rclone + ``` 7. **Add Rclone config for standalone server.** - ```bash - rclone config - ``` - ```rclone - n - Storage > 4 - provider > 7 - env_auth > false - access_key_id - secret_access_key - Region to connect > empty - endpoint > http://192.168.1.220:9040 - location_constraint> empty - acl> empty - server_side_encryption> empty - sse_kms_key_id> empty - Edit advanced config? (y/n) > n - ``` + ```bash + rclone config + ``` + + ```rclone + n + Storage > 4 + provider > 7 + env_auth > false + access_key_id + secret_access_key + Region to connect > empty + endpoint > http://192.168.1.220:9040 + location_constraint> empty + acl> empty + server_side_encryption> empty + sse_kms_key_id> empty + Edit advanced config? (y/n) > n + ``` + 8. **Add Rclone config for K8s server.** - ```bash - rclone config - ``` - ```rclone - n - Storage > 4 - provider > 7 - env_auth > false - access_key_id - secret_access_key - Region to connect > empty - endpoint > http://192.168.1.110:30534 - location_constraint> empty - acl> empty - server_side_encryption> empty - sse_kms_key_id> empty - Edit advanced config? (y/n) > n - ``` -9. **Start copying files.** + ```bash + rclone config + ``` - ```bash - rclone copy --progress --checksum --update ac-standalone: ac-k8s: - ``` + ```rclone + n + Storage > 4 + provider > 7 + env_auth > false + access_key_id + secret_access_key + Region to connect > empty + endpoint > http://192.168.1.110:30534 + location_constraint> empty + acl> empty + server_side_encryption> empty + sse_kms_key_id> empty + Edit advanced config? (y/n) > n + ``` +9. **Start copying files.** + + ```bash + rclone copy --progress --checksum --update ac-standalone: ac-k8s: + ``` ### 5. Vault Backup & Restore @@ -490,49 +607,55 @@ kubectl create secret generic appcircle-server-minio-connection \ 2. **Change directory to appcircle-server.** 3. **Create a file named `migrate.hcl`.** - ```bash - cat > migrate.hcl <<'EOL' - storage_source "file" { - path = "/vault/data/" - } - storage_destination "file" { - path = "/vault/target/" - } + ```bash + cat > migrate.hcl <<'EOL' + storage_source "file" { + path = "/vault/data/" + } - cluster_addr="http://127.0.0.1:8201" - EOL - ``` + storage_destination "file" { + path = "/vault/target/" + } + + cluster_addr="http://127.0.0.1:8201" + EOL + ``` 4. **Get the Vault container name.** - ```bash - docker ps | grep vault - ``` + + ```bash + docker ps | grep vault + ``` 5. **Copy the file into the container.** - ```bash - docker cp migrate.hcl spacetech-vault-1:/vault/ - ``` + + ```bash + docker cp migrate.hcl spacetech-vault-1:/vault/ + ``` 6. **Migrate the the Vault data to the target directory.** - ```bash - docker exec -it spacetech-vault-1 vault operator migrate --config=/vault/migrate.hcl - ``` + + ```bash + docker exec -it spacetech-vault-1 vault operator migrate --config=/vault/migrate.hcl + ``` 7. **Make a tarball with of the data.** - ```bash - docker exec -it spacetech-vault-1 sh -c "cd /vault && tar -czpvf vaultd.tar.gz -C /vault/target/ ." - ``` + + ```bash + docker exec -it spacetech-vault-1 sh -c "cd /vault && tar -czpvf vaultd.tar.gz -C /vault/target/ ." + ``` 8. **Copy the tarball from the container to the host machine.** - ```bash - docker cp spacetech-vault-1:/vault/vaultd.tar.gz . - ``` + + ```bash + docker cp spacetech-vault-1:/vault/vaultd.tar.gz . + ``` 9. **Get the full path of the copied tarball.** - ```bash - realpath vaultd.tar.gz - ``` + ```bash + realpath vaultd.tar.gz + ``` @@ -544,50 +667,59 @@ kubectl create secret generic appcircle-server-minio-connection \ #### Bastion Host 1. **Copy the vault data tar ball to the local.** - ```bash - scp rhel8:/home/berk/ac-script-self-hosted/vaultd.tar.gz . - ``` + + ```bash + scp rhel8:/home/berk/ac-script-self-hosted/vaultd.tar.gz . + ``` 2. **Get the Vault statefulset name.** - ```bash - kubectl get statefulsets -n appcircle | grep vault - ``` + + ```bash + kubectl get statefulsets -n appcircle | grep vault + ``` 3. **Edit the vault `statefulset` for safe operations.** - ```bash - kubectl patch statefulset -n appcircle appcircle-server-vault -p '{"spec": {"template": {"spec":{"containers":[{"name":"vault","command": ["sh", "-c", "tail -f /dev/null" ], "args": null, "readinessProbe": null, "lifecycle": null }]}}}}' - ``` + + ```bash + kubectl patch statefulset -n appcircle appcircle-server-vault -p '{"spec": {"template": {"spec":{"containers":[{"name":"vault","command": ["sh", "-c", "tail -f /dev/null" ], "args": null, "readinessProbe": null, "lifecycle": null }]}}}}' + ``` 4. **Delete the pod for it to be re-created.** - ```bash - kubectl delete pod appcircle-server-vault-0 -n appcircle - ``` + + ```bash + kubectl delete pod appcircle-server-vault-0 -n appcircle + ``` 5. **Copy the vault data to the target pod.** - ```bash - kubectl cp "./vaultd.tar.gz" "appcircle-server-vault-0:/vault/data/vaultd.tar.gz" -n appcircle - ``` + + ```bash + kubectl cp "./vaultd.tar.gz" "appcircle-server-vault-0:/vault/data/vaultd.tar.gz" -n appcircle + ``` 6. **Open shell in the vault container.** - ```bash - kubectl exec -it appcircle-server-vault-0 -- bash - ``` + + ```bash + kubectl exec -it appcircle-server-vault-0 -- bash + ``` 7. **Run the following commands in the shell.** - ```bash - cd /vault/data - tar -xzvf vaultd.tar.gz -C . - /usr/local/bin/docker-entrypoint.sh vault server -config=/vault/config/extraconfig-from-values.hcl - ``` + + ```bash + cd /vault/data + tar -xzvf vaultd.tar.gz -C . + /usr/local/bin/docker-entrypoint.sh vault server -config=/vault/config/extraconfig-from-values.hcl + ``` 8. **Don't close the upper terminal until the process finishes.** 9. **Open a new terminal in the vault container.** - ```bash - kubectl exec -it appcircle-server-vault-0 -- bash - ``` + + ```bash + kubectl exec -it appcircle-server-vault-0 -- bash + ``` 10. **Unseal the vault with the saved keys from the steps above.** + ```bash vault operator unseal dnaDMnwLuRni******M0EPJ2gAlyeHmOAy vault operator unseal FRTs/BO606ty******1nm9pJssLZjqVULR @@ -595,6 +727,7 @@ kubectl create secret generic appcircle-server-minio-connection \ ``` 11. **Delete the vault data tar ball** + ```bash rm /vault/data/vaultd.tar.gz ``` @@ -614,12 +747,13 @@ kubectl create secret generic appcircle-server-minio-connection \ 2. Remove the `resourcesPreset` from the `values.yaml`. 3. Upgrade the Helm release. - ```bash - helm upgrade --install appcircle-server appcircle/appcircle \ - --timeout 1200s \ - -n appcircle \ - -f values.yaml - ``` + + ```bash + helm upgrade --install appcircle-server appcircle/appcircle \ + --timeout 1200s \ + -n appcircle \ + -f values.yaml + ``` 4. **Verification:** After the Kubernetes deployment completes, thoroughly test all Appcircle functionalities. From 14a9bfcf0786ccfab835c5169bacc4f0a37db5e4 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Tue, 14 Jan 2025 12:13:18 +0300 Subject: [PATCH 07/40] update MinIO migration --- .../configuration/docker-k8s-migration.md | 338 +++++++++--------- 1 file changed, 169 insertions(+), 169 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md index d5197de0b..3e1717b9c 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md @@ -35,7 +35,7 @@ This migration process involves downtime. To minimize disruption, **plan accordi - Notify users about the expected downtime and migration schedule. ::: -## Pre-Migration +## Pre-Migration Steps ### Standalone Appcircle Server Steps @@ -101,35 +101,30 @@ On the **standalone Appcircle server**, execute the following commands to back u #### 3. Check the Data Size on the Standalone Appcircle Server -- Get the volume sizes: - -```bash -export APPCIRCLE_DISK_USAGE=$(docker system df -v) -``` - -- Check the MinIO data size: - -```bash -echo "$APPCIRCLE_DISK_USAGE" | grep "snsd_data" -``` - -- Check the MongoDB data size: - -```bash -echo "$APPCIRCLE_DISK_USAGE" | grep "mongo_data" -``` +- **Get the volume sizes:** + ```bash + export APPCIRCLE_DISK_USAGE=$(docker system df -v) + ``` -- Check the PostgreSQL data size: +- **Check the MinIO data size:** + ```bash + echo "$APPCIRCLE_DISK_USAGE" | grep "snsd_data" + ``` -```bash -echo "$APPCIRCLE_DISK_USAGE" | grep "posgresqlData" -``` +- **Check the MongoDB data size:** + ```bash + echo "$APPCIRCLE_DISK_USAGE" | grep "mongo_data" + ``` -- Check the Vault data size: +- **Check the PostgreSQL data size:** + ```bash + echo "$APPCIRCLE_DISK_USAGE" | grep "posgresqlData" + ``` -```bash -echo "$APPCIRCLE_DISK_USAGE" | grep "vault_data" -``` +- **Check the Vault data size:** + ```bash + echo "$APPCIRCLE_DISK_USAGE" | grep "vault_data" + ``` You will use that values while configuring the `values.yaml` of the Appcircle server Helm chart. @@ -212,7 +207,7 @@ After reviewing the key considerations, follow the [Appcircle Server Kubernetes This section details the creation of Kubernetes secrets required for Appcircle to function correctly. These secrets store sensitive information such as passwords, and certificates, securely injecting them into your Appcircle deployment. :::tip -Ensure you have [gathered all necessary data](#pre-migration-backup-and-preparation) before proceeding. +Ensure you have [gathered all necessary data](#2-backup-appcircle-configuration-data) before proceeding. Some secret data, such as database passwords and Keycloak client secrets, used in the Kubernetes secrets creation below should match the data extracted from the backups of the standalone server. Ensure consistency between the backed-up values and the values used in the Kubernetes secrets to prevent connectivity and authentication issues. ::: @@ -271,7 +266,7 @@ kubectl create secret generic appcircle-server-smtp \ --from-file=password= ``` -- **Keycloak Clients Secret:** Create the Keycloak client secrets. +- **Keycloak Clients Secret:** :::caution The client secret values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.clients` key on the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. @@ -317,10 +312,10 @@ kubectl create secret generic appcircle-tls-wildcard \ --type=kubernetes.io/tls ``` -- **MinIO Connection Secret:** Extract the `secretKey` from `generated-secret.yaml`. +- **MinIO Connection Secret:** :::caution -The MinIO keys used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.password` key for the `adminPassword` and `.keycloak.initialPassword` for the `initialPassword` on the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. +The MinIO keys used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.minio.secretKey` key on the `generated-secret.yaml` file for the `accessKey` and `root-password` in the example command below. Using incorrect values will prevent Appcircle from functioning correctly. ::: ```bash @@ -336,19 +331,19 @@ kubectl create secret generic appcircle-server-minio-connection \ #### Standalone Appcircle Server -1. **Locate PostgreSQL Container:**: Find the PostgreSQL container name. +1. **Locate PostgreSQL Container:** Find the PostgreSQL container name. ```bash docker ps | grep postgres ``` -2. **Dump Database:** +2. **Dump Database:** Save the database data to a file. ```bash - docker exec pg_dump -U -h localhost -p 5432 -F c -b -v -f pgdump.backup + docker exec pg_dump -U keycloak -h localhost -p 5432 -F c -b -v -f pgdump.backup keycloak ``` -3. **Copy Dump:** +3. **Copy Dump:** Copy the file from container to Appcircle server host. ```bash docker cp :/pgdump.backup ~/appcircle-k8s-migration/ ``` @@ -356,34 +351,33 @@ kubectl create secret generic appcircle-server-minio-connection \ #### Bastion Host 1. **Copy the PostgreSQL Data to Bastion Host**: Copy the dumped PostgreSQL data from the Appcircle server to the bastion host. + ```bash + scp rhel8:/home/berk/ac-script-self-hosted/projects/spacetech/export/mongo-backup.gz . + ``` 2. **Get PostgreSQL Password:** - ```bash kubectl get secret -n appcircle appcircle-server-auth-postgresql -ojsonpath='{.data.password}' | base64 -d ``` 3. **Get the PostgreSQL pod name:** - ```bash kubectl get pods -n appcircle | grep postgres ``` -4. **Start Port Forwarding:** - +4. **Install PostgreSQL tools:** ```bash - kubectl port-forward appcircle-server-auth-postgresql-0 5432:5432 -n appcircle + brew install postgresql ``` -5. **Install PostgreSQL tools:** - +5. **Start Port Forwarding:** ```bash - brew install postgresql + kubectl port-forward appcircle-server-auth-postgresql-0 5432:5432 -n appcircle ``` -6. **Restore Database:** +6. **Restore the Database:** ```bash - pg_restore -h localhost -p 5432 -U -d ~/appcircle-k8s-migration/pgdump.backup + pg_restore -h localhost -p 5432 -U keycloak -d keycloak ~/appcircle-k8s-migration/pgdump.backup ``` ### 3. MongoDB Backup & Restore @@ -392,65 +386,67 @@ kubectl create secret generic appcircle-server-minio-connection \ -1. **Expose MongoDB Port:** Add a port mapping (e.g., 36300:36300) to your `docker-compose.yml` for the `mongo_1` service and restart. - - ```bash - vim projects/spacetech/export/compose.yaml - ``` - - ```yaml - services: - mongo_1: - image: europe-west1-docker.pkg.dev/appcircle/docker-registry/mongo:v3.25.0 - ports: - - "36300:36300" - ``` - -2. **Change directory to appcircle-server.** - -3. **Get the MongoDB connection string:** - - ```bash - cat projects/spacetech/export/publish/default.env | grep "CUSTOMCONNSTR_PUBLISH_DB_CONNECTION_STRING" - ``` - -4. **Install `mongosh` tool.** To install `mongosh` to your Appcircle server, please check the [official MongoDB documentation](https://www.mongodb.com/docs/mongodb-shell/install/). +1. **Change directory to appcircle-server.** + ```bash + cd appcircle-server + ``` -5. **Open Mongo Shell to the standalone Appcircle server:** +2. **Expose MongoDB Port:** Add a port mapping (e.g., 36300:36300) to your `docker-compose.yml` for the `mongo_1` service and restart. + - Edit the `compose.yaml` file. + ```bash + vim projects/spacetech/export/compose.yaml + ``` + - Add `ports` key to the `mongo_1` service. + ```yaml + services: + mongo_1: + image: europe-west1-docker.pkg.dev/appcircle/docker-registry/mongo:v3.25.0 + ports: + - "36300:36300" + ``` + - Restart the services. + ```bash + ./ac-self-hosted -n spacetech up + ``` - ```bash - mongosh --host 127.0.0.1 --port 36300 - ``` +3. **Install `mongosh` tool.** -6. **Switch to the `admin` db:** + To install `mongosh` to your Appcircle server, please check the [official MongoDB documentation](https://www.mongodb.com/docs/mongodb-shell/install/). - ```mongosh - use admin - ``` +4. **Open Mongo Shell to the standalone Appcircle server:** + ```bash + mongosh --host 127.0.0.1 --port 36300 + ``` -7. **Create a user to dump the DB:** +5. **Switch to the `admin` db:** + ```mongosh + use admin + ``` - ```mongosh - db.createUser({user: "backup",pwd: "backup",roles: [{ role: "root", db: "admin"}]}) - ``` +6. **Create a user to dump the DB:** + ```mongosh + db.createUser({user: "backup",pwd: "backup",roles: [{ role: "root", db: "admin"}]}) + ``` -8. **Get the MongoDB container names:** +7. **Get the MongoDB container name:** + ```bash + docker ps | grep mongo_1 + ``` - ```bash - docker ps | grep mongo_1 - ``` +8. **Get the MongoDB connection string:** + ```bash + cat projects/spacetech/export/publish/default.env | grep "CUSTOMCONNSTR_PUBLISH_DB_CONNECTION_STRING" + ``` 9. **Dump the MongoDB:** - -```bash -docker exec -it spacetech-mongo_1-1 mongodump --uri="mongodb://backup:backup@mongo_1:36300,mongo_2:36301,mongo_3:36302/?replicaSet=rs&authSource=admin" --gzip --archive=/mongo-backup.gz -``` + ```bash + docker exec -it spacetech-mongo_1-1 mongodump --uri="mongodb://backup:backup@mongo_1:36300,mongo_2:36301,mongo_3:36302/?replicaSet=rs&authSource=admin" --gzip --archive=/mongo-backup.gz + ``` 11. **Copy the dumped DB file from out of the container to the host machine:** - -```bash -docker cp spacetech-mongo_1-1:/mongo-backup.gz . -``` + ```bash + docker cp spacetech-mongo_1-1:/mongo-backup.gz . + ``` #### Bastion Host @@ -460,15 +456,11 @@ docker cp spacetech-mongo_1-1:/mongo-backup.gz . scp rhel8:/home/berk/ac-script-self-hosted/projects/spacetech/export/mongo-backup.gz . ``` -2. **Install mongo tools:** - - ```bash - brew tap mongodb/brew - brew install mongodb-database-tools - ``` +2. **Install MongoDB Database Tools:** + + To install MongoDB Database Tools, please check the [official MongoDB documentation](https://www.mongodb.com/docs/database-tools/installation/installation/#installation). 3. **Get the MongoDB root password of the K8s installation:** - ```bash kubectl get secret -n appcircle appcircle-server-mongodb -o jsonpath='{.data.mongodb-root-password}' | base64 -d ``` @@ -479,7 +471,7 @@ docker cp spacetech-mongo_1-1:/mongo-backup.gz . ``` 5. **Restore the dumped MongoDB:** ```bash - mongorestore --uri="mongodb://root:cgmITFkJuT@localhost:27017/?authSource=admin" --gzip --archive=./mongo-backup.gz + mongorestore --uri="mongodb://root:@localhost:27017/?authSource=admin" --gzip --archive=./mongo-backup.gz ``` ### 4. MinIO Mirror @@ -489,29 +481,26 @@ docker cp spacetech-mongo_1-1:/mongo-backup.gz . 1. **Login to the standalone Appcircle server.** 2. **Change directory to appcircle-server.** + ```bash + cd appcircle-server + ``` 3. **Expose MinIO Port:** Ensure MinIO's port 9000 is accessible. You might need to publish the port in your `docker-compose.yml`. - ```bash - docker ps | grep snsd - ``` + ```bash + docker ps | grep snsd + ``` 4. **Get MinIO credentials:** Retrieve the access key and secret key from your MinIO configuration. - ```bash - cat projects/spacetech/export/minio/access.env - ``` + ```bash + cat projects/spacetech/export/minio/access.env + ``` #### Bastion Host 1. **Login to the bastion.** -2. **Install the `mc` tool:** - - ```bash - brew install minio-mc - ``` - 3. **Get the Kubernetes MinIO access and secret keys.** ```bash @@ -528,69 +517,80 @@ docker cp spacetech-mongo_1-1:/mongo-backup.gz . 5. **Change MinIO service to NodePort for temporary.** - :::info - We recommend opening the MinIO service to the external network temporarily instead of using `kubectl port-forward` since we had problems while migrating large files over `kubectl`. + :::info + We recommend opening the MinIO service to the external network temporarily instead of using `kubectl port-forward` since you might have problems while transferring large files over port forwarding of the `kubectl`. - Note that this doesn't make the MinIO data public as long as you keep the MinIO password a secret. - ::: + Note that this doesn't make the MinIO data public as long as you keep the MinIO password secret. + ::: - ```bash - kubectl patch service appcircle-server-minio -n appcircle --type='json' -p='[{"op": "replace", "path": "/spec/type", "value": "NodePort"}, {"op": "add", "path": "/spec/ports/0/nodePort", "value": 30534}, {"op": "add", "path": "/spec/ports/1/nodePort", "value": 32761}]' - ``` + ```bash + kubectl patch service appcircle-server-minio -n appcircle --type='json' -p='[{"op": "replace", "path": "/spec/type", "value": "NodePort"}, {"op": "add", "path": "/spec/ports/0/nodePort", "value": 30534}, {"op": "add", "path": "/spec/ports/1/nodePort", "value": 32761}]' + ``` 6. **Install `rclone` tool.** - :::info - We recommended using `rclone` tool instead of `mc`. - ::: - - ```bash - brew install rclone - ``` - -7. **Add Rclone config for standalone server.** - - ```bash - rclone config - ``` - - ```rclone - n - Storage > 4 - provider > 7 - env_auth > false - access_key_id - secret_access_key - Region to connect > empty - endpoint > http://192.168.1.220:9040 - location_constraint> empty - acl> empty - server_side_encryption> empty - sse_kms_key_id> empty - Edit advanced config? (y/n) > n - ``` - -8. **Add Rclone config for K8s server.** - - ```bash - rclone config - ``` - - ```rclone - n - Storage > 4 - provider > 7 - env_auth > false - access_key_id - secret_access_key - Region to connect > empty - endpoint > http://192.168.1.110:30534 - location_constraint> empty - acl> empty - server_side_encryption> empty - sse_kms_key_id> empty - Edit advanced config? (y/n) > n - ``` + :::info + We recommended using `rclone` tool instead of `mc`. + ::: + + + To install `rclone`, please check the [official rclone documentation](https://rclone.org/install/). + +7. **Add Rclone Configuration for Standalone Server** + + To configure Rclone for the standalone Appcircle server, follow these steps: + + - Start the Rclone configuration process: + ```bash + rclone config + ``` + + - Use the following inputs during the configuration process: + + ```plaintext + n # Create a new remote + name> ac-standalone # Provide a descriptive name for the remote + Storage> 4 # Select "Amazon S3 Compliant Storage Provider" (4) + provider> 7 # Select "Minio Object Storage" (7) + env_auth> "false" # Set environment authentication to "false" + access_key_id> # Enter the standalone Appcircle server's access key + secret_access_key> # Enter the standalone Appcircle server's secret access key + region> # Leave this empty + endpoint> # Provide the standalone Appcircle server's IP and MinIO port. Example: http://192.168.1.220:9040 + location_constraint: # Leave this empty + acl: # Leave this empty + server_side_encryption: # Leave this empty + sse_kms_key_id: # Leave this empty + Edit advanced config? (y/n): n # Skip advanced configuration + ``` + +8. **Add Rclone config for Kubernetes Appcircle server.** + + To configure `rclone` for the Kubernetes Appcircle server, follow these steps: + + - Start the `rclone` configuration process: + ```bash + rclone config + ``` + + - Use the following inputs during the configuration process: + + ```plaintext + n # Create a new remote + name> ac-k8s # Provide a descriptive name for the remote + Storage> 4 # Select "Amazon S3 Compliant Storage Provider" (4) + provider> 7 # Select "Minio Object Storage" (7) + env_auth> "false" # Set environment authentication to "false" + access_key_id> # Enter the standalone Appcircle server's access key + secret_access_key> # Enter the standalone Appcircle server's secret access key + region> # Leave this empty + endpoint> # Provide the standalone Appcircle server's IP and MinIO port. Example: http://192.168.1.220:9040 + location_constraint: # Leave this empty + acl: # Leave this empty + server_side_encryption: # Leave this empty + sse_kms_key_id: # Leave this empty + Edit advanced config? (y/n): n # Skip advanced configuration + ``` 9. **Start copying files.** From 67ef2eb939f58985cee47baccb832687fafb9474 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Tue, 14 Jan 2025 12:32:02 +0300 Subject: [PATCH 08/40] update vault and post migration parts --- .../configuration/docker-k8s-migration.md | 88 ++++++++++++------- 1 file changed, 54 insertions(+), 34 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md index 3e1717b9c..59353edbd 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md @@ -16,9 +16,11 @@ This guide provides a step-by-step walkthrough for migrating your self-hosted ** 1. A fully operational Docker deployment of Appcircle server. 2. A Kubernetes cluster ready for deployment. -In this guide, the **bastion host** refers to a machine with network access to both: +In this guide, the **standalone Appcircle server** refers to the machine that hosts the Appcircle server with Docker. -- The existing Appcircle server. +Also the **bastion host** refers to a machine with network access to both: + +- The existing standalone Appcircle server. - The Kubernetes cluster. The bastion host serves as a central point for executing commands, transferring backup data, and applying configurations. During the migration process, you will: @@ -26,6 +28,7 @@ The bastion host serves as a central point for executing commands, transferring - Copy configuration files and database backups from the Docker host to the bastion host. - Use the bastion host to deploy and configure the new Appcircle instance in the Kubernetes cluster. + :::caution Downtime Alert This migration process involves downtime. To minimize disruption, **plan accordingly** and: @@ -605,9 +608,11 @@ kubectl create secret generic appcircle-server-minio-connection \ 1. **Login to the standalone Appcircle server.** 2. **Change directory to appcircle-server.** + ```bash + cd appcircle-server + ``` 3. **Create a file named `migrate.hcl`.** - ```bash cat > migrate.hcl <<'EOL' storage_source "file" { @@ -623,31 +628,26 @@ kubectl create secret generic appcircle-server-minio-connection \ ``` 4. **Get the Vault container name.** - ```bash docker ps | grep vault ``` -5. **Copy the file into the container.** - +5. **Copy the migration file to the Vault container.** ```bash docker cp migrate.hcl spacetech-vault-1:/vault/ ``` 6. **Migrate the the Vault data to the target directory.** - ```bash docker exec -it spacetech-vault-1 vault operator migrate --config=/vault/migrate.hcl ``` -7. **Make a tarball with of the data.** - +7. **Create a tarball of the Vault data.** ```bash docker exec -it spacetech-vault-1 sh -c "cd /vault && tar -czpvf vaultd.tar.gz -C /vault/target/ ." ``` -8. **Copy the tarball from the container to the host machine.** - +8. **Copy the tarball to the host machine.** ```bash docker cp spacetech-vault-1:/vault/vaultd.tar.gz . ``` @@ -666,44 +666,37 @@ kubectl create secret generic appcircle-server-minio-connection \ #### Bastion Host -1. **Copy the vault data tar ball to the local.** - +1. **Copy the vault data tar ball to the bastion host.** ```bash scp rhel8:/home/berk/ac-script-self-hosted/vaultd.tar.gz . ``` 2. **Get the Vault statefulset name.** - ```bash kubectl get statefulsets -n appcircle | grep vault ``` 3. **Edit the vault `statefulset` for safe operations.** - ```bash kubectl patch statefulset -n appcircle appcircle-server-vault -p '{"spec": {"template": {"spec":{"containers":[{"name":"vault","command": ["sh", "-c", "tail -f /dev/null" ], "args": null, "readinessProbe": null, "lifecycle": null }]}}}}' ``` 4. **Delete the pod for it to be re-created.** - ```bash kubectl delete pod appcircle-server-vault-0 -n appcircle ``` 5. **Copy the vault data to the target pod.** - ```bash kubectl cp "./vaultd.tar.gz" "appcircle-server-vault-0:/vault/data/vaultd.tar.gz" -n appcircle ``` 6. **Open shell in the vault container.** - ```bash kubectl exec -it appcircle-server-vault-0 -- bash ``` 7. **Run the following commands in the shell.** - ```bash cd /vault/data tar -xzvf vaultd.tar.gz -C . @@ -713,13 +706,11 @@ kubectl create secret generic appcircle-server-minio-connection \ 8. **Don't close the upper terminal until the process finishes.** 9. **Open a new terminal in the vault container.** - ```bash kubectl exec -it appcircle-server-vault-0 -- bash ``` 10. **Unseal the vault with the saved keys from the steps above.** - ```bash vault operator unseal dnaDMnwLuRni******M0EPJ2gAlyeHmOAy vault operator unseal FRTs/BO606ty******1nm9pJssLZjqVULR @@ -727,7 +718,6 @@ kubectl create secret generic appcircle-server-minio-connection \ ``` 11. **Delete the vault data tar ball** - ```bash rm /vault/data/vaultd.tar.gz ``` @@ -740,21 +730,51 @@ kubectl create secret generic appcircle-server-minio-connection \ --patch='{"stringData": { "token": "*hvs*.U5LLy********F2bOy", "unseal_keys": "dnaDMnwLuRni******M0EPJ2gAlyeHmOAy FRTs/BO606ty******1nm9pJssLZjqVULR f35t4MU6gojw******/bH92wR9t6MzzIYc" }}' ``` -## Post-Migration Steps +## Post-Migration Steps -1. Remove the `replicas: 0` from the `values.yaml`. +After completing the migration, follow these steps to finalize and verify the setup: -2. Remove the `resourcesPreset` from the `values.yaml`. +### 1. Update the `values.yaml` -3. Upgrade the Helm release. +- **Remove Keycloak Replica Override:** + Delete the `replicas: 0` setting under `auth-keycloak`. - ```bash - helm upgrade --install appcircle-server appcircle/appcircle \ - --timeout 1200s \ - -n appcircle \ - -f values.yaml - ``` +- **Remove MongoDB Resource Preset:** + Delete the `resourcesPreset` setting under `mongodb` if you don't need. + +### 2. Upgrade the Helm Release +Apply the updated `values.yaml` configuration to the Appcircle server Helm chart: + +```bash +helm upgrade --install appcircle-server appcircle/appcircle \ + --timeout 1200s \ + -n appcircle \ + -f values.yaml +``` + +### 3. Update DNS Records + +- **Shift DNS to the New Cluster:** + Update the DNS records to point to the new Appcircle Kubernetes cluster. + +- **Redis Subdomain Change:** + Replace the `redis` subdomain from the standalone server (e.g., `redis.appcircle.spacetech.com`) with the `kvs` subdomain for Kubernetes (e.g., `kvs.appcircle.spacetech.com`). + +- **Reference:** + For detailed instructions, see the [DNS Records Section](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/installation/kubernetes#1-add-dns-records). + +### 4. Verification + +- Test the following functionalities and ensure all data and features are operational post-migration. + - **Builds** + - **Publish** + - **Enterprise App Store** + - **Testing Distribution** + - **LDAP / SSO Settings** + +### 5. Clean Up -4. **Verification:** After the Kubernetes deployment completes, thoroughly test all Appcircle functionalities. +Once the migration has been confirmed as successful: -5. **Clean Up:** Once the migration is successful and verified, remove the old Docker containers and data. +- Remove old Docker containers from the standalone Appcircle server. +- Delete any residual data no longer needed. From 4369e31bc6e3059cf27f49b1e1fefc10cc56f9b2 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Tue, 14 Jan 2025 12:33:22 +0300 Subject: [PATCH 09/40] change local names to example names --- .../helm-chart/configuration/docker-k8s-migration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md index 59353edbd..672298dfc 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md @@ -355,7 +355,7 @@ kubectl create secret generic appcircle-server-minio-connection \ 1. **Copy the PostgreSQL Data to Bastion Host**: Copy the dumped PostgreSQL data from the Appcircle server to the bastion host. ```bash - scp rhel8:/home/berk/ac-script-self-hosted/projects/spacetech/export/mongo-backup.gz . + scp standalone-appcircle-server/app/appcircle-server/projects/spacetech/export/mongo-backup.gz . ``` 2. **Get PostgreSQL Password:** @@ -456,7 +456,7 @@ kubectl create secret generic appcircle-server-minio-connection \ 1. **Copy the file from the standalone Appcircle server to the bastion host:** ```bash - scp rhel8:/home/berk/ac-script-self-hosted/projects/spacetech/export/mongo-backup.gz . + scp standalone-appcircle-server/app/appcircle-server/projects/spacetech/export/mongo-backup.gz . ``` 2. **Install MongoDB Database Tools:** @@ -668,7 +668,7 @@ kubectl create secret generic appcircle-server-minio-connection \ 1. **Copy the vault data tar ball to the bastion host.** ```bash - scp rhel8:/home/berk/ac-script-self-hosted/vaultd.tar.gz . + scp standalone-appcircle-server/app/appcircle-server/vaultd.tar.gz . ``` 2. **Get the Vault statefulset name.** From a1e108dd18f82a1e97c31ecfb87257df37ee826a Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Tue, 14 Jan 2025 13:03:32 +0300 Subject: [PATCH 10/40] grammar and formatting fixes --- .../configuration/docker-k8s-migration.md | 452 ++++++++++-------- 1 file changed, 247 insertions(+), 205 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md index 672298dfc..b745f5afc 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md @@ -28,7 +28,6 @@ The bastion host serves as a central point for executing commands, transferring - Copy configuration files and database backups from the Docker host to the bastion host. - Use the bastion host to deploy and configure the new Appcircle instance in the Kubernetes cluster. - :::caution Downtime Alert This migration process involves downtime. To minimize disruption, **plan accordingly** and: @@ -69,34 +68,34 @@ mkdir appcircle-k8s-migration && cd appcircle-k8s-migration On the **standalone Appcircle server**, execute the following commands to back up the necessary files. Transfer the outputs to the migration directory on the bastion host. -- **Appcircle Server Directory** +- **Appcircle Server Directory:** Change directory to the `appcircle-server`. ```bash cd appcircle-server ``` -- **Global Configuration** +- **`global.yaml` Configuration:** Print the `global.yaml` file and save it on the bastion host: ```bash cat projects/spacetech/global.yaml ``` -- **User Secrets** +- **User Secrets:** Decode and print the `user-secret.yaml` file and save it on the bastion host: ```bash cat projects/spacetech/user-secret | base64 -d ``` -- **Generated Secrets** +- **Generated Secrets:** Print the `generated-secret.yaml` file and save it on the bastion host: ```bash cat projects/spacetech/generated-secret.yaml ``` -- **Cred Json** +- **`cred.json` file:** Print the `cred.json` file and save it on the bastion host: ```bash cat cred.json @@ -105,31 +104,35 @@ On the **standalone Appcircle server**, execute the following commands to back u #### 3. Check the Data Size on the Standalone Appcircle Server - **Get the volume sizes:** - ```bash - export APPCIRCLE_DISK_USAGE=$(docker system df -v) - ``` + + ```bash + export APPCIRCLE_DISK_USAGE=$(docker system df -v) + ``` - **Check the MinIO data size:** - ```bash - echo "$APPCIRCLE_DISK_USAGE" | grep "snsd_data" - ``` + + ```bash + echo "$APPCIRCLE_DISK_USAGE" | grep "snsd_data" + ``` - **Check the MongoDB data size:** - ```bash - echo "$APPCIRCLE_DISK_USAGE" | grep "mongo_data" - ``` + + ```bash + echo "$APPCIRCLE_DISK_USAGE" | grep "mongo_data" + ``` - **Check the PostgreSQL data size:** - ```bash - echo "$APPCIRCLE_DISK_USAGE" | grep "posgresqlData" - ``` + + ```bash + echo "$APPCIRCLE_DISK_USAGE" | grep "posgresqlData" + ``` - **Check the Vault data size:** - ```bash - echo "$APPCIRCLE_DISK_USAGE" | grep "vault_data" - ``` + ```bash + echo "$APPCIRCLE_DISK_USAGE" | grep "vault_data" + ``` -You will use that values while configuring the `values.yaml` of the Appcircle server Helm chart. +You will use those values while configuring the `values.yaml` of the Appcircle server Helm chart. #### 4. Make Sure the Standalone Appcircle Server Is Running @@ -142,22 +145,22 @@ Additionally: To achieve that, you can follow the steps below: -1. **Login to the standalone Appcircle server.** +1. **Log in to the standalone Appcircle server:** -2. **Change directory to the `appcircle-server`.** +2. **Change directory to the `appcircle-server`:** ```bash cd appcircle-server ``` -3. **Change directory to the `export` directory of the project.** +3. **Change directory to the `export` directory of the project:** ```bash cd projects/spacetech/export ``` -4. **Stop the Nginx service.** +4. **Stop the Nginx service:** ```bash docker compose stop nginx ``` @@ -172,24 +175,24 @@ After reviewing the key considerations, follow the [Appcircle Server Kubernetes #### 2. Key Considerations -- **Stateful Applications** +- **Stateful Applications:** This guide assumes you are migrating from a standalone Appcircle server to a Kubernetes cluster with stateful applications (e.g., PostgreSQL, MinIO, MongoDB, Vault) managed by the Appcircle Helm chart. - If you choose to manage stateful apps **outside the Helm chart's scope**, modify the commands and configurations accordingly. - Refer to the [Production Readiness](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/configuration/production-readiness) page for additional guidance. -- **Protocol Configuration (HTTP/HTTPS)** +- **Protocol Configuration (HTTP/HTTPS):** Match the protocol used by your standalone Appcircle server: - If the standalone server is using `HTTPS`, configure the Helm chart for `HTTPS`. - If the server is running on `HTTP`, adjust the Helm chart configuration for `HTTP`. -- **Storage Allocation** +- **Storage Allocation:** Update your Helm chart's `values.yaml` file with storage sizes based on the data extracted in the [Check the Data Size](#3-check-the-data-size-on-the-standalone-appcircle-server) section. - Refer to the [Storage Configuration](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/configuration/storage-configuration) page for detailed instructions. -- **Prepare `values.yaml` for Migration** +- **Prepare `values.yaml` for Migration:** Make the following adjustments to your `values.yaml` file **before deploying the Helm chart**: ```yaml @@ -207,7 +210,7 @@ After reviewing the key considerations, follow the [Appcircle Server Kubernetes ### 1. Create Kubernetes Secrets -This section details the creation of Kubernetes secrets required for Appcircle to function correctly. These secrets store sensitive information such as passwords, and certificates, securely injecting them into your Appcircle deployment. +This section details the creation of Kubernetes secrets required for Appcircle to function correctly. These secrets store sensitive information such as passwords and certificates, securely injecting them into your Appcircle deployment. :::tip Ensure you have [gathered all necessary data](#2-backup-appcircle-configuration-data) before proceeding. @@ -221,7 +224,7 @@ Some secret data, such as database passwords and Keycloak client secrets, used i kubectl create namespace appcircle ``` -- **Container Registry Secret:** Create the container registry secret for Appcircle artifact registry: +- **Container Registry Secret:** Create the container registry secret for the Appcircle artifact registry: :::info If you are using your own container registry, follow the `Custom Registry` section below. @@ -272,7 +275,7 @@ kubectl create secret generic appcircle-server-smtp \ - **Keycloak Clients Secret:** :::caution -The client secret values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.clients` key on the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. +The client secret values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.clients` key in the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. ::: ```bash @@ -294,7 +297,7 @@ kubectl create secret generic appcircle-server-auth-keycloak-clients-secret \ - **Keycloak Passwords Secret:** :::caution -The keycloak password values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.password` key for the `adminPassword` and `.keycloak.initialPassword` for the `initialPassword` on the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. +The Keycloak password values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.password` key for the `adminPassword` and `.keycloak.initialPassword` for the `initialPassword` in the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. ::: ```bash @@ -304,7 +307,7 @@ kubectl create secret generic appcircle-server-auth-keycloak-passwords \ --from-literal=adminPassword= ``` -- **SSL Certificate Secret:** If you are using the Appcircle with HTTPS, create secret for SSL certificates. +- **SSL Certificate Secret:** If you are using the Appcircle with HTTPS, create a secret for SSL certificates. ```bash kubectl create secret generic appcircle-tls-wildcard \ @@ -318,7 +321,7 @@ kubectl create secret generic appcircle-tls-wildcard \ - **MinIO Connection Secret:** :::caution -The MinIO keys used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.minio.secretKey` key on the `generated-secret.yaml` file for the `accessKey` and `root-password` in the example command below. Using incorrect values will prevent Appcircle from functioning correctly. +The MinIO keys used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.minio.secretKey` key in the `generated-secret.yaml` file for the `accessKey` and `root-password` in the example command below. Using incorrect values will prevent Appcircle from functioning correctly. ::: ```bash @@ -354,26 +357,31 @@ kubectl create secret generic appcircle-server-minio-connection \ #### Bastion Host 1. **Copy the PostgreSQL Data to Bastion Host**: Copy the dumped PostgreSQL data from the Appcircle server to the bastion host. + ```bash scp standalone-appcircle-server/app/appcircle-server/projects/spacetech/export/mongo-backup.gz . ``` 2. **Get PostgreSQL Password:** + ```bash kubectl get secret -n appcircle appcircle-server-auth-postgresql -ojsonpath='{.data.password}' | base64 -d ``` 3. **Get the PostgreSQL pod name:** + ```bash kubectl get pods -n appcircle | grep postgres ``` 4. **Install PostgreSQL tools:** + ```bash brew install postgresql ``` 5. **Start Port Forwarding:** + ```bash kubectl port-forward appcircle-server-auth-postgresql-0 5432:5432 -n appcircle ``` @@ -389,64 +397,77 @@ kubectl create secret generic appcircle-server-minio-connection \ -1. **Change directory to appcircle-server.** - ```bash - cd appcircle-server - ``` +1. **Change directory to appcircle-server:** + + ```bash + cd appcircle-server + ``` 2. **Expose MongoDB Port:** Add a port mapping (e.g., 36300:36300) to your `docker-compose.yml` for the `mongo_1` service and restart. - - Edit the `compose.yaml` file. - ```bash - vim projects/spacetech/export/compose.yaml - ``` - - Add `ports` key to the `mongo_1` service. - ```yaml - services: - mongo_1: - image: europe-west1-docker.pkg.dev/appcircle/docker-registry/mongo:v3.25.0 - ports: - - "36300:36300" - ``` - - Restart the services. - ```bash - ./ac-self-hosted -n spacetech up - ``` -3. **Install `mongosh` tool.** + - Edit the `compose.yaml` file. + + ```bash + vim projects/spacetech/export/compose.yaml + ``` + + - Add the `ports` key to the `mongo_1` service. + + ```yaml + services: + mongo_1: + image: europe-west1-docker.pkg.dev/appcircle/docker-registry/mongo:v3.25.0 + ports: + - "36300:36300" + ``` + + - Restart the services. + + ```bash + ./ac-self-hosted -n spacetech up + ``` + +3. **Install the `mongosh` tool.** - To install `mongosh` to your Appcircle server, please check the [official MongoDB documentation](https://www.mongodb.com/docs/mongodb-shell/install/). + To install `mongosh` on the standalone Appcircle server, please check the [official MongoDB documentation](https://www.mongodb.com/docs/mongodb-shell/install/). 4. **Open Mongo Shell to the standalone Appcircle server:** - ```bash - mongosh --host 127.0.0.1 --port 36300 - ``` + + ```bash + mongosh --host 127.0.0.1 --port 36300 + ``` 5. **Switch to the `admin` db:** - ```mongosh - use admin - ``` + + ```mongosh + use admin + ``` 6. **Create a user to dump the DB:** - ```mongosh - db.createUser({user: "backup",pwd: "backup",roles: [{ role: "root", db: "admin"}]}) - ``` + + ```mongosh + db.createUser({user: "backup",pwd: "backup",roles: [{ role: "root", db: "admin"}]}) + ``` 7. **Get the MongoDB container name:** - ```bash - docker ps | grep mongo_1 - ``` + + ```bash + docker ps | grep mongo_1 + ``` 8. **Get the MongoDB connection string:** - ```bash - cat projects/spacetech/export/publish/default.env | grep "CUSTOMCONNSTR_PUBLISH_DB_CONNECTION_STRING" - ``` + + ```bash + cat projects/spacetech/export/publish/default.env | grep "CUSTOMCONNSTR_PUBLISH_DB_CONNECTION_STRING" + ``` 9. **Dump the MongoDB:** - ```bash - docker exec -it spacetech-mongo_1-1 mongodump --uri="mongodb://backup:backup@mongo_1:36300,mongo_2:36301,mongo_3:36302/?replicaSet=rs&authSource=admin" --gzip --archive=/mongo-backup.gz - ``` -11. **Copy the dumped DB file from out of the container to the host machine:** + ```bash + docker exec -it spacetech-mongo_1-1 mongodump --uri="mongodb://backup:backup@mongo_1:36300,mongo_2:36301,mongo_3:36302/?replicaSet=rs&authSource=admin" --gzip --archive=/mongo-backup.gz + ``` + +10. **Copy the dumped DB file from out of the container to the host machine:** ```bash docker cp spacetech-mongo_1-1:/mongo-backup.gz . ``` @@ -459,11 +480,12 @@ kubectl create secret generic appcircle-server-minio-connection \ scp standalone-appcircle-server/app/appcircle-server/projects/spacetech/export/mongo-backup.gz . ``` -2. **Install MongoDB Database Tools:** - - To install MongoDB Database Tools, please check the [official MongoDB documentation](https://www.mongodb.com/docs/database-tools/installation/installation/#installation). +2. **Install MongoDB Database Tools:** + + To install MongoDB Database Tools, please check the [official MongoDB documentation](https://www.mongodb.com/docs/database-tools/installation/installation/#installation). 3. **Get the MongoDB root password of the K8s installation:** + ```bash kubectl get secret -n appcircle appcircle-server-mongodb -o jsonpath='{.data.mongodb-root-password}' | base64 -d ``` @@ -481,30 +503,31 @@ kubectl create secret generic appcircle-server-minio-connection \ #### Standalone Appcircle Server -1. **Login to the standalone Appcircle server.** +1. **Log in to the standalone Appcircle server:** -2. **Change directory to appcircle-server.** - ```bash - cd appcircle-server - ``` +2. **Change directory to appcircle-server:** + + ```bash + cd appcircle-server + ``` 3. **Expose MinIO Port:** Ensure MinIO's port 9000 is accessible. You might need to publish the port in your `docker-compose.yml`. - ```bash - docker ps | grep snsd - ``` + ```bash + docker ps | grep snsd + ``` 4. **Get MinIO credentials:** Retrieve the access key and secret key from your MinIO configuration. - ```bash - cat projects/spacetech/export/minio/access.env - ``` + ```bash + cat projects/spacetech/export/minio/access.env + ``` #### Bastion Host -1. **Login to the bastion.** +1. **Log in to the bastion:** -3. **Get the Kubernetes MinIO access and secret keys.** +2. **Get the Kubernetes MinIO access and secret keys:** ```bash kubectl get secret -n appcircle appcircle-server-minio-connection -ojsonpath='{.data.accessKey}' | base64 -d && \ @@ -512,90 +535,91 @@ kubectl create secret generic appcircle-server-minio-connection \ kubectl get secret -n appcircle appcircle-server-minio-connection -ojsonpath='{.data.secretKey}' | base64 -d ``` -4. **Get the MinIO service name.** +3. **Get the MinIO service name:** ```bash kubectl get services -n appcircle | grep minio ``` -5. **Change MinIO service to NodePort for temporary.** +4. **Change MinIO service to NodePort for temporary:** - :::info - We recommend opening the MinIO service to the external network temporarily instead of using `kubectl port-forward` since you might have problems while transferring large files over port forwarding of the `kubectl`. + :::info + We recommend opening the MinIO service to the external network temporarily instead of using `kubectl port-forward` since you might have problems while transferring large files over port forwarding of the `kubectl`. - Note that this doesn't make the MinIO data public as long as you keep the MinIO password secret. - ::: + Note that this doesn't make the MinIO data public as long as you keep the MinIO password secret. + ::: - ```bash - kubectl patch service appcircle-server-minio -n appcircle --type='json' -p='[{"op": "replace", "path": "/spec/type", "value": "NodePort"}, {"op": "add", "path": "/spec/ports/0/nodePort", "value": 30534}, {"op": "add", "path": "/spec/ports/1/nodePort", "value": 32761}]' - ``` + ```bash + kubectl patch service appcircle-server-minio -n appcircle --type='json' -p='[{"op": "replace", "path": "/spec/type", "value": "NodePort"}, {"op": "add", "path": "/spec/ports/0/nodePort", "value": 30534}, {"op": "add", "path": "/spec/ports/1/nodePort", "value": 32761}]' + ``` + +5. **Install `rclone` tool:** + + :::info + We recommended using `rclone` tool instead of `mc`. + ::: + + To install `rclone`, please check the [official rclone documentation](https://rclone.org/install/). + +6. **Add Rclone Configuration for Standalone Server:** -6. **Install `rclone` tool.** - - :::info - We recommended using `rclone` tool instead of `mc`. - ::: - - - To install `rclone`, please check the [official rclone documentation](https://rclone.org/install/). - -7. **Add Rclone Configuration for Standalone Server** - - To configure Rclone for the standalone Appcircle server, follow these steps: - - - Start the Rclone configuration process: - ```bash - rclone config - ``` - - - Use the following inputs during the configuration process: - - ```plaintext - n # Create a new remote - name> ac-standalone # Provide a descriptive name for the remote - Storage> 4 # Select "Amazon S3 Compliant Storage Provider" (4) - provider> 7 # Select "Minio Object Storage" (7) - env_auth> "false" # Set environment authentication to "false" - access_key_id> # Enter the standalone Appcircle server's access key - secret_access_key> # Enter the standalone Appcircle server's secret access key - region> # Leave this empty - endpoint> # Provide the standalone Appcircle server's IP and MinIO port. Example: http://192.168.1.220:9040 - location_constraint: # Leave this empty - acl: # Leave this empty - server_side_encryption: # Leave this empty - sse_kms_key_id: # Leave this empty - Edit advanced config? (y/n): n # Skip advanced configuration - ``` - -8. **Add Rclone config for Kubernetes Appcircle server.** - - To configure `rclone` for the Kubernetes Appcircle server, follow these steps: - - - Start the `rclone` configuration process: - ```bash - rclone config - ``` - - - Use the following inputs during the configuration process: - - ```plaintext - n # Create a new remote - name> ac-k8s # Provide a descriptive name for the remote - Storage> 4 # Select "Amazon S3 Compliant Storage Provider" (4) - provider> 7 # Select "Minio Object Storage" (7) - env_auth> "false" # Set environment authentication to "false" - access_key_id> # Enter the standalone Appcircle server's access key - secret_access_key> # Enter the standalone Appcircle server's secret access key - region> # Leave this empty - endpoint> # Provide the standalone Appcircle server's IP and MinIO port. Example: http://192.168.1.220:9040 - location_constraint: # Leave this empty - acl: # Leave this empty - server_side_encryption: # Leave this empty - sse_kms_key_id: # Leave this empty - Edit advanced config? (y/n): n # Skip advanced configuration - ``` - -9. **Start copying files.** + To configure Rclone for the standalone Appcircle server, follow these steps: + + - Start the Rclone configuration process: + + ```bash + rclone config + ``` + + - Use the following inputs during the configuration process: + + ```plaintext + n # Create a new remote + name> ac-standalone # Provide a descriptive name for the remote + Storage> 4 # Select "Amazon S3 Compliant Storage Provider" (4) + provider> 7 # Select "Minio Object Storage" (7) + env_auth> "false" # Set environment authentication to "false" + access_key_id> # Enter the standalone Appcircle server's access key + secret_access_key> # Enter the standalone Appcircle server's secret access key + region> # Leave this empty + endpoint> # Provide the standalone Appcircle server's IP and MinIO port. Example: http://192.168.1.220:9040 + location_constraint: # Leave this empty + acl: # Leave this empty + server_side_encryption: # Leave this empty + sse_kms_key_id: # Leave this empty + Edit advanced config? (y/n): n # Skip advanced configuration + ``` + +7. **Add Rclone config for Kubernetes Appcircle server:** + + To configure `rclone` for the Kubernetes Appcircle server, follow these steps: + + - Start the `rclone` configuration process: + + ```bash + rclone config + ``` + + - Use the following inputs during the configuration process: + + ```plaintext + n # Create a new remote + name> ac-k8s # Provide a descriptive name for the remote + Storage> 4 # Select "Amazon S3 Compliant Storage Provider" (4) + provider> 7 # Select "Minio Object Storage" (7) + env_auth> "false" # Set environment authentication to "false" + access_key_id> # Enter the standalone Appcircle server's access key + secret_access_key> # Enter the standalone Appcircle server's secret access key + region> # Leave this empty + endpoint> # Provide the standalone Appcircle server's IP and MinIO port. Example: http://192.168.1.220:9040 + location_constraint: # Leave this empty + acl: # Leave this empty + server_side_encryption: # Leave this empty + sse_kms_key_id: # Leave this empty + Edit advanced config? (y/n): n # Skip advanced configuration + ``` + +8. **Start copying files:** ```bash rclone copy --progress --checksum --update ac-standalone: ac-k8s: @@ -605,14 +629,16 @@ kubectl create secret generic appcircle-server-minio-connection \ #### Standalone Server Steps -1. **Login to the standalone Appcircle server.** +1. **Log in to the standalone Appcircle server:** -2. **Change directory to appcircle-server.** - ```bash - cd appcircle-server - ``` +2. **Change directory to appcircle-server:** + + ```bash + cd appcircle-server + ``` + +3. **Create a file named `migrate.hcl`:** -3. **Create a file named `migrate.hcl`.** ```bash cat > migrate.hcl <<'EOL' storage_source "file" { @@ -627,123 +653,139 @@ kubectl create secret generic appcircle-server-minio-connection \ EOL ``` -4. **Get the Vault container name.** +4. **Get the Vault container name:** + ```bash docker ps | grep vault ``` -5. **Copy the migration file to the Vault container.** +5. **Copy the migration file to the Vault container:** + ```bash docker cp migrate.hcl spacetech-vault-1:/vault/ ``` -6. **Migrate the the Vault data to the target directory.** +6. **Migrate the the Vault data to the target directory:** + ```bash docker exec -it spacetech-vault-1 vault operator migrate --config=/vault/migrate.hcl ``` -7. **Create a tarball of the Vault data.** +7. **Create a tarball of the Vault data:** + ```bash docker exec -it spacetech-vault-1 sh -c "cd /vault && tar -czpvf vaultd.tar.gz -C /vault/target/ ." ``` -8. **Copy the tarball to the host machine.** +8. **Copy the tarball to the host machine:** + ```bash docker cp spacetech-vault-1:/vault/vaultd.tar.gz . ``` -9. **Get the full path of the copied tarball.** +9. **Get the full path of the copied tarball:** ```bash realpath vaultd.tar.gz ``` -10. **Get the unseal and root keys and save, you will use for unsealing the vault.** +10. **Get the unseal and root keys and save, you will use for unsealing the vault:** ```bash grep -A 7 "vault" projects/spacetech/generated-secret.yaml ``` #### Bastion Host -1. **Copy the vault data tar ball to the bastion host.** +1. **Copy the vault data tar ball to the bastion host:** + ```bash scp standalone-appcircle-server/app/appcircle-server/vaultd.tar.gz . ``` -2. **Get the Vault statefulset name.** +2. **Get the Vault statefulset name:** + ```bash kubectl get statefulsets -n appcircle | grep vault ``` -3. **Edit the vault `statefulset` for safe operations.** +3. **Edit the vault `statefulset` for safe operations:** + ```bash kubectl patch statefulset -n appcircle appcircle-server-vault -p '{"spec": {"template": {"spec":{"containers":[{"name":"vault","command": ["sh", "-c", "tail -f /dev/null" ], "args": null, "readinessProbe": null, "lifecycle": null }]}}}}' ``` -4. **Delete the pod for it to be re-created.** +4. **Delete the pod for it to be re-created:** + ```bash kubectl delete pod appcircle-server-vault-0 -n appcircle ``` -5. **Copy the vault data to the target pod.** +5. **Copy the vault data to the target pod:** + ```bash kubectl cp "./vaultd.tar.gz" "appcircle-server-vault-0:/vault/data/vaultd.tar.gz" -n appcircle ``` -6. **Open shell in the vault container.** +6. **Open shell in the vault container:** + ```bash kubectl exec -it appcircle-server-vault-0 -- bash ``` -7. **Run the following commands in the shell.** +7. **Run the following commands in the shell:** + ```bash cd /vault/data tar -xzvf vaultd.tar.gz -C . /usr/local/bin/docker-entrypoint.sh vault server -config=/vault/config/extraconfig-from-values.hcl ``` -8. **Don't close the upper terminal until the process finishes.** +8. **Don't close the upper terminal until the process finishes:** + +9. **Open a new terminal in the vault container:** -9. **Open a new terminal in the vault container.** ```bash kubectl exec -it appcircle-server-vault-0 -- bash ``` -10. **Unseal the vault with the saved keys from the steps above.** +10. **Unseal the vault with the saved keys from the steps above:** + ```bash vault operator unseal dnaDMnwLuRni******M0EPJ2gAlyeHmOAy vault operator unseal FRTs/BO606ty******1nm9pJssLZjqVULR vault operator unseal f35t4MU6gojw******/bH92wR9t6MzzIYc ``` -11. **Delete the vault data tar ball** +11. **Delete the vault data tar ball:** + ```bash rm /vault/data/vaultd.tar.gz ``` -12. **Exit from the first and second vault terminal.** +12. **Exit from the first and second vault terminal:** -13. **Edit the secret with old unseal keys.** +13. **Edit the secret with old unseal keys:** ```bash kubectl patch secret appcircle-server-vault-seal -n appcircle \ --patch='{"stringData": { "token": "*hvs*.U5LLy********F2bOy", "unseal_keys": "dnaDMnwLuRni******M0EPJ2gAlyeHmOAy FRTs/BO606ty******1nm9pJssLZjqVULR f35t4MU6gojw******/bH92wR9t6MzzIYc" }}' ``` -## Post-Migration Steps +## Post-Migration Steps -After completing the migration, follow these steps to finalize and verify the setup: +After completing the migration, follow these steps to finalize and verify the setup: ### 1. Update the `values.yaml` - **Remove Keycloak Replica Override:** - Delete the `replicas: 0` setting under `auth-keycloak`. + Delete the `replicas: 0` setting under `auth-keycloak`. - **Remove MongoDB Resource Preset:** - Delete the `resourcesPreset` setting under `mongodb` if you don't need. + Delete the `resourcesPreset` setting under `mongodb` if you don't need it. ### 2. Upgrade the Helm Release -Apply the updated `values.yaml` configuration to the Appcircle server Helm chart: + +Apply the updated `values.yaml` configuration to the Appcircle server Helm chart: ```bash helm upgrade --install appcircle-server appcircle/appcircle \ @@ -758,23 +800,23 @@ helm upgrade --install appcircle-server appcircle/appcircle \ Update the DNS records to point to the new Appcircle Kubernetes cluster. - **Redis Subdomain Change:** - Replace the `redis` subdomain from the standalone server (e.g., `redis.appcircle.spacetech.com`) with the `kvs` subdomain for Kubernetes (e.g., `kvs.appcircle.spacetech.com`). + Replace the `redis` subdomain from the standalone server (e.g., `redis.appcircle.spacetech.com`) with the `kvs` subdomain for Kubernetes (e.g., `kvs.appcircle.spacetech.com`). - **Reference:** For detailed instructions, see the [DNS Records Section](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/installation/kubernetes#1-add-dns-records). ### 4. Verification -- Test the following functionalities and ensure all data and features are operational post-migration. - - **Builds** +- Test the following functionalities and ensure all data and features are operational post-migration. + - **Builds** - **Publish** - - **Enterprise App Store** + - **Enterprise App Store** - **Testing Distribution** - **LDAP / SSO Settings** ### 5. Clean Up -Once the migration has been confirmed as successful: +Once the migration has been confirmed as successful: -- Remove old Docker containers from the standalone Appcircle server. +- Remove old Docker containers from the standalone Appcircle server. - Delete any residual data no longer needed. From 8cde037b10004f4e068c74305e7fcfa7a3f5e5fa Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Tue, 14 Jan 2025 16:29:33 +0300 Subject: [PATCH 11/40] added keycloak extra settings --- .../helm-chart/configuration/docker-k8s-migration.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md index b745f5afc..dc314d790 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md @@ -199,6 +199,8 @@ After reviewing the key considerations, follow the [Appcircle Server Kubernetes auth: auth-keycloak: replicas: 0 + organizationName: spacetech + initialOrganizationId: a0c5c671-35a7-47a9-a32d-eaf4edac574a mongodb: resourcesPreset: "large" ``` From 9b67f420fc8e410e8d37c7db1bbee98d48d21ae4 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Wed, 15 Jan 2025 10:37:34 +0300 Subject: [PATCH 12/40] document moved --- .../{configuration => installation}/docker-k8s-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename docs/self-hosted-appcircle/install-server/helm-chart/{configuration => installation}/docker-k8s-migration.md (99%) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md similarity index 99% rename from docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md rename to docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index dc314d790..3d07ad05f 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -2,7 +2,7 @@ title: Docker to Kubernetes Migration description: Learn how to migrate from standalone Appcircle server to Kubernetes Appcircle server. tags: [self-hosted, helm, configuration, kubernetes, migration] -sidebar_position: 95 +sidebar_position: 30 --- import Tabs from '@theme/Tabs'; From 19e32ad6adcbec02703402b5fe2aa70c650dba36 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Wed, 15 Jan 2025 10:41:37 +0300 Subject: [PATCH 13/40] added DNS step --- .../installation/docker-k8s-migration.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 3d07ad05f..49549f1a6 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -37,6 +37,36 @@ This migration process involves downtime. To minimize disruption, **plan accordi - Notify users about the expected downtime and migration schedule. ::: + +## Prerequisites + +To complete this guide, you must have the following: + +### 1. Domain Name + +A main **domain name**, which will have **subdomains**, is **required** for the Appcircle server. Since the standalone Appcircle server already has a configured domain name, you should retain the same domain name when migrating to the Kubernetes cluster. + +:::note +In this documentation, we will use `appcircle.spacetech.com` as an **example main domain** and `spacetech` as an **example organization name**. +::: + +
+ Click to view more details about domain name prerequisite. + +By default, Appcircle uses seven subdomains. These subdomains are: + +1. api.appcircle.spacetech.com +2. auth.appcircle.spacetech.com +3. dist.appcircle.spacetech.com +4. hook.appcircle.spacetech.com +5. resource.appcircle.spacetech.com +6. my.appcircle.spacetech.com +7. redis.appcircle.spacetech.com + +**Upon completing the deployment** of the Appcircle server, you will need to create DNS records based on the Ingress objects created in Kubernetes. + +
+ ## Pre-Migration Steps ### Standalone Appcircle Server Steps From c8c1022e6794e6c56e37c0a2e9d3ffd8b9df2ff4 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Wed, 15 Jan 2025 10:42:17 +0300 Subject: [PATCH 14/40] added SSL step --- .../installation/docker-k8s-migration.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 49549f1a6..be7a54f5d 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -67,6 +67,33 @@ By default, Appcircle uses seven subdomains. These subdomains are: +### 2. SSL Certificate + +An **SSL certificate** is **required** to deploy the Appcircle server for **production** environments. + +You **can skip** SSL certificate if you are deploying Appcircle server **for trial purposes**. + +
+ Click to view more details about SSL certificate prerequisite. + +- The SSL certificate private key shouldn't be password protected. + +- The SSL certificate should be in PEM format. + +- Ensure the **one certificate** covers **all the subdomains** in the [domain name](#1-domain-name) section. + +- Make sure to configure the Appcircle server with a **fullchain certificate**, which should include the leaf (or app) certificate, intermediate certificates, and the root certificate. + +:::tip +You can use a **wildcard certificate** to cover all the subdomains, simplifying the certificate management process. For example, a wildcard certificate for **`*.appcircle.spacetech.com`** will be enough. +::: + +:::caution +If you use a domain like `appcircle.spacetech.com`, it will have **two levels of subdomains**. Ensure that both your DNS provider and SSL certificate provider support multi-level subdomains for proper configuration. +::: + +
+ ## Pre-Migration Steps ### Standalone Appcircle Server Steps From 87d9e4a1ae1c9b6ffd127f970082b828129bfbdb Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Wed, 15 Jan 2025 10:42:48 +0300 Subject: [PATCH 15/40] added cluster steps --- .../installation/docker-k8s-migration.md | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index be7a54f5d..b89f67ada 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -94,6 +94,57 @@ If you use a domain like `appcircle.spacetech.com`, it will have **two levels of +### 3. Kubernetes Cluster + +A **Kubernetes cluster** is **required** to install the Appcircle server using Helm. + +**Minimum hardware requirements for enterprise installation:** + +- Node(s) with `x86_64` architecture +- 8 CPUs +- 16 GB RAM +- 50 GB Disk per node + +:::tip +The required storage size for the Appcircle server depends significantly on the size of the artifacts (APK, IPA, cache). +::: + +
+ Click to view more details about Kubernetes cluster prerequisite. + +**Recommended hardware requirements for enterprise installation:** + +- Nodes with `x86_64` architecture +- 32 CPUs +- 64 GB RAM +- 1 TB Disk + +For production environments, if you deploy stateful applications with the Appcircle Helm chart, you will need significant storage capacity, as specified above. You can configure disk resource allocations through Helm values according to your needs. + +However, if you opt to use external services for components such as PostgreSQL or MinIO, the storage requirements for the cluster are significantly reduced to around 50GB. It is **highly recommended** to deploy stateful apps outside of the Appcircle Helm chart configuration. + +:::tip +For stateful apps that should deployed out of scope this helm chart, you can check the [Production Readiness](/self-hosted-appcircle/install-server/helm-chart/configuration/production-readiness) document. + +For storage details, you can check the [Storage Class Configuration](/self-hosted-appcircle/install-server/helm-chart/configuration/storage-configuration) section. +::: + +:::info +Using SSD storage is highly recommended if stateful applications are installed within the Appcircle Helm chart scope. SSDs provide faster read/write speeds, improving the performance and responsiveness of your applications. +::: + +Additionally, ensure that your Kubernetes version is 1.29.1 or later to maintain compatibility and support. + +
+ +### 4. `kubectl` + +The **`kubectl`** CLI is **required**. + +### 5. Helm v3 + +**Helm version `3.11.0`** or later is **required**. + ## Pre-Migration Steps ### Standalone Appcircle Server Steps From 242d1e94cdfd6e646c53f04a497c3707bc633117 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Wed, 15 Jan 2025 11:09:46 +0300 Subject: [PATCH 16/40] added installation steps --- .../installation/docker-k8s-migration.md | 369 ++++++++++++++++-- 1 file changed, 333 insertions(+), 36 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index b89f67ada..a4b87cad6 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -69,9 +69,9 @@ By default, Appcircle uses seven subdomains. These subdomains are: ### 2. SSL Certificate -An **SSL certificate** is **required** to deploy the Appcircle server for **production** environments. +If the **standalone Appcircle server** is already using **HTTPS**, you **should provide an SSL certificate** for the Appcircle server Kubernetes deployment. -You **can skip** SSL certificate if you are deploying Appcircle server **for trial purposes**. +If the **standalone Appcircle server** uses **HTTP**, you can **skip configuring an SSL certificate**.
Click to view more details about SSL certificate prerequisite. @@ -106,7 +106,9 @@ A **Kubernetes cluster** is **required** to install the Appcircle server using H - 50 GB Disk per node :::tip -The required storage size for the Appcircle server depends significantly on the size of the artifacts (APK, IPA, cache). +The required storage size for the Appcircle server depends significantly on the size of artifacts, such as **APK**, **IPA**, and **cache** files. + +Since you already have a running standalone Appcircle server, you should check its data sizes and **adjust the storage sizes** for the Kubernetes deployment accordingly **by continuing to follow this documentation**. :::
@@ -145,9 +147,111 @@ The **`kubectl`** CLI is **required**. **Helm version `3.11.0`** or later is **required**. -## Pre-Migration Steps -### Standalone Appcircle Server Steps +## Pre-installation Steps + +### 1. Ingress Controller + +The Kubernetes cluster should have **an Ingress controller** installed and configured since Appcircle exposes its services through **Ingress objects**. + +For **trial** purposes, you can **use** the default **Ingress-Nginx** controller deployed **within the Helm chart** scope and skip this section. + +You can check the default Ingress-Nginx controller values and configure as your needs by checking the [Ingress Configuration](/self-hosted-appcircle/install-server/helm-chart/configuration/ingress-configuration.md#appcircle-default-ingress-nginx-configuration) documentation. + +For **production** environments, it's recommended to use **your own Ingress controller**. + +Appcircle server supports Ingress-Nginx controller by default. To install Ingress-Nginx controller to the Kubernetes cluster, please check [the Ingress-Nginx controller documentation](https://kubernetes.github.io/ingress-nginx/deploy/#installation-guide). + +:::info +**Other Ingress controllers** like HAProxy Ingress controller are also **supported** by **modifying Helm values** accordingly. +::: + +#### Enable SSL Passthrough + +You can **skip** this section **if you use the default** Ingress-Nginx controller deployed **within the Helm chart scope**. + +Enable **`ssl-passthrough`** feature on your ingress-controller Enabling the SSL passthrough depends on the Ingress controller that is used in the Kubernetes cluster. For example: + +- For Nginx Ingress controller, you can check [the Nginx documentation](https://kubernetes.github.io/ingress-nginx/user-guide/tls/#ssl-passthrough). + +- For HAProxy Ingress controller, you can check [the HAProxy documentation](https://www.haproxy.com/documentation/kubernetes-ingress/community/configuration-reference/ingress/#ssl-passthrough). + +:::info +Enabling the SSL passthrough option **does not** automatically allow all SSL traffic **from all Ingress objects** to pass through to the original service. Instead, it enables Ingress resources to leverage the SSL passthrough feature, allowing encrypted traffic to reach the backend service without being decrypted by the Ingress controller. +::: + +#### Ingress Configurations + +You can **skip** this section **if you use the default** Ingress-Nginx controller deployed **within the Helm chart scope**. + +Configure the Appcircle ingresses for production usage. For more details, please check the [Ingress Configuration](/self-hosted-appcircle/install-server/helm-chart/configuration/ingress-configuration.md#configuring-ingress-annotations) documentation. + +### 2. Production Readiness + +If you are deploying the Appcircle server for a production environment, it is recommended that stateful applications, such as databases or object storage, be deployed outside the scope of the Appcircle server Helm chart. + +For more information, you can check the [Production Readiness](/self-hosted-appcircle/install-server/helm-chart/configuration/production-readiness) documentation. + +### 3. Create Namespace + +**Create a namespace** for the Appcircle server deployment. In this documentation, we will use `appcircle` as the example namespace. + +```bash +kubectl create namespace appcircle +``` + +### 4. Create Container Registry Secret + +By default, Appcircle uses its own image registry, which requires authentication with the `cred.json` file provided by Appcircle. + +If you are using your own container image registry to access Appcircle container images, you can either skip authentication if your registry doesn't require it or create a secret for your custom registry. + +Follow the steps below to create the registry secret in the `appcircle` namespace for pods to successfully pull images: + +:::info +If you are using your own container registry, follow the `Custom Registry` section below. + +If your registry doesn't require authentication, you can skip this section. +::: + + + + + +- Save the `cred.json` file. + +- Create the container registry secret: + +```bash +kubectl create secret docker-registry containerregistry \ + -n appcircle \ + --docker-server='europe-west1-docker.pkg.dev' \ + --docker-username='_json_key' \ + --docker-password="$(cat cred.json)" +``` + + + + +:::tip +If the `HISTCONTROL` environment variable is set to `ignoreboth`, commands with a leading space character will not be stored in the shell history. This allows you to create secrets safely without storing sensitive information in the shell history. +::: + +- Update the `server`, `username`, and `password` fields for your own custom registry and create the container registry secret: + +```bash +kubectl create secret docker-registry containerregistry \ + -n appcircle \ + --docker-server='registry.spacetech.com' \ + --docker-username='yourRegistryUsername' \ + --docker-password='superSecretRegistryPassword' +``` + + + + + +### 5. Standalone Appcircle Server Steps This section outlines the essential steps to back up data from your existing Standalone Appcircle server installation and prepare your Kubernetes environment for the migration. @@ -242,6 +346,7 @@ On the **standalone Appcircle server**, execute the following commands to back u You will use those values while configuring the `values.yaml` of the Appcircle server Helm chart. + #### 4. Make Sure the Standalone Appcircle Server Is Running Before proceeding with the migration, verify that the standalone Appcircle server is operational and healthy. This ensures you can create accurate backups without issues. @@ -261,60 +366,252 @@ To achieve that, you can follow the steps below: cd appcircle-server ``` -3. **Change directory to the `export` directory of the project:** +3. **Check the health status of the standalone Appcircle server:** + ```bash + ./ac-self-hosted.sh -n spacetech check + ``` + +4. **Change directory to the `export` directory of the project:** ```bash cd projects/spacetech/export ``` -4. **Stop the Nginx service:** +5. **Stop the Nginx service:** ```bash docker compose stop nginx ``` -### Kubernetes Appcircle Server Steps +## Installation -This section outlines the steps and considerations for deploying the Appcircle server to a Kubernetes cluster. Ensure you review the [Key Considerations](#2-key-considerations) below before proceeding. +### 1. Create `values.yaml` -#### 1. Prepare for Helm Chart Installation +Below is a minimal `values.yaml` file that you should configure for your deployment. -After reviewing the key considerations, follow the [Appcircle Server Kubernetes Installation Guide](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/installation/kubernetes) for detailed Appcircle server Helm chart deployment instructions. +**Please adjust these values** according to your environment requirements and **save your file**. -#### 2. Key Considerations +In the example values below, we used `spacetech` as an **example organization name**. You should **replace it** with your actual organization name or any other value you prefer. -- **Stateful Applications:** - This guide assumes you are migrating from a standalone Appcircle server to a Kubernetes cluster with stateful applications (e.g., PostgreSQL, MinIO, MongoDB, Vault) managed by the Appcircle Helm chart. +:::caution +Please **review the comments for the `values.yaml`** below. If the values provided are incompatible, the installation may not complete successfully. Ensure that all configurations are correctly entered to avoid potential issues during the setup process. +::: - - If you choose to manage stateful apps **outside the Helm chart's scope**, modify the commands and configurations accordingly. - - Refer to the [Production Readiness](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/configuration/production-readiness) page for additional guidance. + -- **Protocol Configuration (HTTP/HTTPS):** - Match the protocol used by your standalone Appcircle server: + + +
+ Click to view example `values.yaml` file. + +```yaml +# Global configurations for Appcircle deployment +global: + urls: + # Main domain configuration - All Appcircle services will be subdomains of this domain + domainName: .appcircle.spacetech.com + # SMTP server configuration for sending emails (Authentication, Notifications, Testing Distribution) + mail: + smtp: + # SMTP server host + host: "smtp.spacetech.com" + # SMTP Server port, 587 typically used for StartTLS + port: "587" + # Email address that will be used as sender + from: "appcircle@yandex.com" + # SSL configuration - Set to 'true' if the SMTP server uses SSL/TLS protocol for secure communication, typically on port 465. + ssl: "false" + # StartTLS configuration - Set to 'true' if the SMTP server uses StartTLS protocol, typically on port 587. + tls: "true" + # SMTP authentication settings + auth: "true" + username: "appcircle-smtp-user" + password: "superSecretSmtpPassword" + +# Authentication configuration +auth: + auth-keycloak: + # Initial admin user email for Appcircle server + initialUsername: "admin@spacetech.com" +``` - - If the standalone server is using `HTTPS`, configure the Helm chart for `HTTPS`. - - If the server is running on `HTTP`, adjust the Helm chart configuration for `HTTP`. +
-- **Storage Allocation:** - Update your Helm chart's `values.yaml` file with storage sizes based on the data extracted in the [Check the Data Size](#3-check-the-data-size-on-the-standalone-appcircle-server) section. + + - - Refer to the [Storage Configuration](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/configuration/storage-configuration) page for detailed instructions. +
+ Click to view example `values.yaml` file. + +```yaml +# Global configurations for Appcircle deployment +global: + urls: + # Main domain configuration - All Appcircle services will be subdomains of this domain + domainName: .appcircle.spacetech.com + # Protocol to be used for connections + scheme: https + + # SMTP server configuration for sending emails (Authentication, Notifications, Testing Distribution) + mail: + smtp: + # SMTP server host + host: smtp.spacetech.com + # SMTP Server port, 587 typically used for StartTLS + port: 587 + # Email address that will be used as sender + from: appcircle@spacetech.com + # SSL configuration - Set to 'true' if the SMTP server uses SSL/TLS protocol for secure communication, typically on port 465. + ssl: "false" + # StartTLS configuration - Set to 'true' if the SMTP server uses StartTLS protocol, typically on port 587. + tls: "true" + # SMTP authentication settings + auth: "true" + username: smtpUserName + # You can create a secret with the password or directly enter the password here. + password: superSecretSmtpPassword + + # If the K8s cluster access the container images from a private container image registry, you can configure it here. + # Container Image Registry host for container images + imageRegistry: europe-west1-docker.pkg.dev + # Container Image Repository path between registry host and image name + imageRepositoryPath: appcircle/docker-registry + + # Kubernetes Ingress controller class + ingressClassName: "nginx" + + # SSL/TLS certificate configuration for HTTPS + # You can create a secret with the certificate and key or directly enter them here. + tlsWildcard: + # Public certificate - Fullchain including leaf (app), intermediate and root SSL certificates + cert: | + -----BEGIN CERTIFICATE----- + MIIFzTCCBLWgAwIBAgISBMLn5uQI6Wmzku14xXUbbIbmMA0GCSqGSIb3DQEBCwUA + ... + SA== + -----END CERTIFICATE----- + -----BEGIN CERTIFICATE----- + MIIFBjCCAu6gAwIBAgIRAIp9PhPWLzDvI4a9KQdrNPgwDQYJKoZIhvcNAQELBQAw + ... + uYkQ4omYCTX5ohy+knMjdOmdH9c7SpqEWBDC86fiNex+O0XOMEZSa8DA + -----END CERTIFICATE----- + -----BEGIN CERTIFICATE----- + MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw + ... + emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc= + -----END CERTIFICATE----- + # Private key for the SSL certificate + key: | + -----BEGIN PRIVATE KEY----- + MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQC3wS87baGONXjr + ... + oUcjMAu/mGJjtn9AS0S7rRa58Q== + -----END PRIVATE KEY----- + # Certificate Authority public key - Typically the bottom certificate of the fullchain SSL certificate + caCert: | + -----BEGIN CERTIFICATE----- + MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw + ... + emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc= + -----END CERTIFICATE----- +# Authentication configuration +auth: + auth-keycloak: + # Organization name for Appcircle server + organizationName: spacetech + # Initial admin user email for Appcircle server + initialUsername: "admin@example.com" + # Initial admin password - Should contain: min 6 chars, 1 lowercase, 1 uppercase, 1 number + # You can create a secret with the password or directly enter the password here + initialPassword: "superSecretAppcirclePassword1234" + image: + # Appcircle keycloak image repository path + repository: europe-west1-docker.pkg.dev/appcircle/docker-registry/appcircle-keycloak + +# Internal Ingress controller configuration +ingress-nginx: + enabled: false + +# Appcircle vault configuration +vault: + server: + image: + # Appcircle vault image repository path + repository: europe-west1-docker.pkg.dev/appcircle/docker-registry/appcircle-vault + +# Web event Redis configuration +webeventredis: + # Enable TLS for Redis connections + tls: + enabled: true + # Ingress configuration for Redis + ingress: + enabled: true + tls: true +``` -- **Prepare `values.yaml` for Migration:** - Make the following adjustments to your `values.yaml` file **before deploying the Helm chart**: +
- ```yaml - auth: - auth-keycloak: - replicas: 0 - organizationName: spacetech - initialOrganizationId: a0c5c671-35a7-47a9-a32d-eaf4edac574a - mongodb: - resourcesPreset: "large" - ``` + + + +### 2. Remove Sensitive Information From `values.yaml` + +**Remove sensitive information** such as Appcircle initial user password, SMTP password, SSL certificates, and other secrets from the `values.yaml` **for production environments**, by checking the [Sensitive Values](/self-hosted-appcircle/install-server/helm-chart/configuration/sensitive-configuration) documentation. + +### 3. Prepare `values.yaml` for Migration +**Make the following adjustments** to your `values.yaml` file **before deploying the Helm chart**: + +```yaml +auth: + auth-keycloak: + replicas: 0 + organizationName: spacetech + initialOrganizationId: a0c5c671-35a7-47a9-a32d-eaf4edac574a +mongodb: + resourcesPreset: "large" +``` + +- Setting `auth-keycloak.replicas` to `0` disables Keycloak authentication during migration to prevent conflicts. +- Setting `resourcesPreset` to `"large"` ensures MongoDB has sufficient resources for handling large datasets. + + +### 4. Add the Appcircle Helm Repository + +**Add the Appcircle Helm repository** to the configuration of Helm: + +```bash +helm repo add appcircle https://helm-package.appcircle.io && \ +helm repo update +``` + +### 5. Install the Appcircle Server - - Setting `auth-keycloak.replicas` to `0` disables Keycloak authentication during migration to prevent conflicts. - - Setting `resourcesPreset` to `"large"` ensures MongoDB has sufficient resources for handling large datasets. +**Run the following Helm command** to install the Appcircle server chart. + +In this example, we deploy the Appcircle server to a single namespace, using **`appcircle`** as the **namespace** and **`appcircle-server`** as the Helm **release name**. + +```bash +helm install appcircle-server appcircle/appcircle \ + --timeout 1200s \ + -n appcircle \ + -f values.yaml +``` + +:::warning +If you need or want to change the release name, please note that it should be 18 characters or fewer. +::: + +You can watch the Appcircle server installation with any Kubernetes monitoring tool. The installation process duration depends on factors such as network speed and the processing power of your Kubernetes nodes. Typically, the installation may take up to **10 to 15 minutes**. + +To make sure that the Appcircle server is installed successfully, you can run the command below and wait to finish: + +```bash +kubectl wait --for=condition=ready pod \ + -l app.kubernetes.io/instance=appcircle-server \ + -n appcircle --timeout 1200s && \ + echo "Appcircle is ready to use. Happy building! " +``` ## Migrate the Data From b24e76897caf7302af4c5769cd6ae9d2afa0cd94 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Wed, 15 Jan 2025 11:16:26 +0300 Subject: [PATCH 17/40] added storage updates --- .../helm-chart/installation/docker-k8s-migration.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index a4b87cad6..0fcb9db5d 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -560,7 +560,18 @@ webeventredis: **Remove sensitive information** such as Appcircle initial user password, SMTP password, SSL certificates, and other secrets from the `values.yaml` **for production environments**, by checking the [Sensitive Values](/self-hosted-appcircle/install-server/helm-chart/configuration/sensitive-configuration) documentation. ### 3. Prepare `values.yaml` for Migration -**Make the following adjustments** to your `values.yaml` file **before deploying the Helm chart**: + +**Make the following adjustments** to your `values.yaml` file **before deploying the Helm chart**. + +#### Storage Updates + +After [checking the data size](#3-check-the-data-size-on-the-standalone-appcircle-server) on the standalone Appcircle server, ensure that you adjust the storage size accordingly. The configured storage must meet or exceed the data size requirements to support the migration and ongoing usage of the Appcircle server. + +For detailed instructions on configuring storage sizes in the `values.yaml`, refer to the [storage configuration](/self-hosted-appcircle/install-server/helm-chart/configuration/storage-configuration) page. + +#### General Updates + +Please check the `values.yaml` below and configure your `values.yaml` according to this. ```yaml auth: From fcd8bccb93201b79808525e28917dbcfe50f0945 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Wed, 15 Jan 2025 14:10:57 +0300 Subject: [PATCH 18/40] added screenshots and optimized --- .../installation/docker-k8s-migration.md | 351 +++++++++++------- 1 file changed, 226 insertions(+), 125 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 0fcb9db5d..ca621b9fc 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -8,6 +8,8 @@ sidebar_position: 30 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import SpacetechExampleInfo from '@site/docs/self-hosted-appcircle/install-server/linux-package/configure-server/\_spacetech-example-info.mdx'; +import Screenshot from '@site/src/components/Screenshot'; +import NeedHelp from '@site/docs/\_need-help.mdx'; ## Overview @@ -15,6 +17,7 @@ This guide provides a step-by-step walkthrough for migrating your self-hosted ** 1. A fully operational Docker deployment of Appcircle server. 2. A Kubernetes cluster ready for deployment. +3. A bastion host. In this guide, the **standalone Appcircle server** refers to the machine that hosts the Appcircle server with Docker. @@ -28,7 +31,7 @@ The bastion host serves as a central point for executing commands, transferring - Copy configuration files and database backups from the Docker host to the bastion host. - Use the bastion host to deploy and configure the new Appcircle instance in the Kubernetes cluster. -:::caution Downtime Alert +:::caution Downtime Caution This migration process involves downtime. To minimize disruption, **plan accordingly** and: - Back up all crucial data before starting the migration. @@ -37,7 +40,6 @@ This migration process involves downtime. To minimize disruption, **plan accordi - Notify users about the expected downtime and migration schedule. ::: - ## Prerequisites To complete this guide, you must have the following: @@ -147,6 +149,21 @@ The **`kubectl`** CLI is **required**. **Helm version `3.11.0`** or later is **required**. +### 6. Bastion Host + +The bastion host should meet the following requirements to facilitate the migration from the standalone Appcircle server to the Kubernetes Appcircle server: + +- **SSH Access**: The bastion host must have SSH access to the standalone Appcircle server. + +- **Kubernetes Access**: The bastion host must be able to access the Kubernetes cluster for deploying the Helm chart and performing other tasks. + +- **Hardware Requirements**: + - 2 CPUs + - 4 GB RAM + - Sufficient disk space for migration tasks. The disk space requirement will depend on the total size of the **PostgreSQL**, **MongoDB**, and **Vault** data of the standalone Appcircle server. You can easily see the data size of the standalone Appcircle server by checking [this section](#3-check-the-data-size-on-the-standalone-appcircle-server). + - **MinIO disk space** is not a concern, as the data is directly copied between the source and target servers without being stored on the bastion host. + +Ensure the bastion host has enough storage to temporarily hold any necessary migration files, but do not expect it to store the data long-term. ## Pre-installation Steps @@ -250,7 +267,6 @@ kubectl create secret docker-registry containerregistry \ - ### 5. Standalone Appcircle Server Steps This section outlines the essential steps to back up data from your existing Standalone Appcircle server installation and prepare your Kubernetes environment for the migration. @@ -294,7 +310,7 @@ On the **standalone Appcircle server**, execute the following commands to back u ``` - **User Secrets:** - Decode and print the `user-secret.yaml` file and save it on the bastion host: + Decode and print the `user-secret` file and save it on the bastion host: ```bash cat projects/spacetech/user-secret | base64 -d @@ -324,61 +340,70 @@ On the **standalone Appcircle server**, execute the following commands to back u - **Check the MinIO data size:** ```bash - echo "$APPCIRCLE_DISK_USAGE" | grep "snsd_data" + echo "$APPCIRCLE_DISK_USAGE" | grep "spacetech_snsd_data" ``` - **Check the MongoDB data size:** ```bash - echo "$APPCIRCLE_DISK_USAGE" | grep "mongo_data" + echo "$APPCIRCLE_DISK_USAGE" | grep "spacetech_mongo_data" ``` - **Check the PostgreSQL data size:** ```bash - echo "$APPCIRCLE_DISK_USAGE" | grep "posgresqlData" + echo "$APPCIRCLE_DISK_USAGE" | grep "spacetech_posgresqlData" ``` - **Check the Vault data size:** ```bash - echo "$APPCIRCLE_DISK_USAGE" | grep "vault_data" + echo "$APPCIRCLE_DISK_USAGE" | grep "spacetech_vault_data" ``` You will use those values while configuring the `values.yaml` of the Appcircle server Helm chart. - #### 4. Make Sure the Standalone Appcircle Server Is Running Before proceeding with the migration, verify that the standalone Appcircle server is operational and healthy. This ensures you can create accurate backups without issues. -Additionally: - -- There should be no running builds on the Appcircle during the migration. -- Prevent external requests while keeping the server healthy by stopping the Nginx service. - -To achieve that, you can follow the steps below: +- **Log in to the standalone Appcircle server:** -1. **Log in to the standalone Appcircle server:** - -2. **Change directory to the `appcircle-server`:** +- **Change directory to the `appcircle-server`:** ```bash cd appcircle-server ``` -3. **Check the health status of the standalone Appcircle server:** +- **Check the health status of the standalone Appcircle server:** + ```bash ./ac-self-hosted.sh -n spacetech check ``` -4. **Change directory to the `export` directory of the project:** +#### 5. Update the Standalone Appcircle Server to the Latest Version + +Before migrating to Kubernetes Appcircle server, please [update the standalone Appcircle server](https://docs.appcircle.io/self-hosted-appcircle/install-server/linux-package/update) to the latest version. + +#### 6. Stop the Standalone Appcircle Server Requests. + +For the migration, there should be no running builds on the Appcircle during the migration. Also prevent external requests while keeping the server healthy by stopping the Nginx service. + +- **Log in to the standalone Appcircle server:** + +- **Change directory to the `appcircle-server`:** + ```bash + cd appcircle-server + ``` + +- **Change directory to the `export` directory of the project:** + ```bash cd projects/spacetech/export ``` -5. **Stop the Nginx service:** +- **Stop the Nginx service:** ```bash docker compose stop nginx ``` @@ -411,6 +436,7 @@ global: # Main domain configuration - All Appcircle services will be subdomains of this domain domainName: .appcircle.spacetech.com # SMTP server configuration for sending emails (Authentication, Notifications, Testing Distribution) + # Use the same SMTP settings as specified in the `global.yaml` file of the standalone Appcircle server. mail: smtp: # SMTP server host @@ -418,14 +444,14 @@ global: # SMTP Server port, 587 typically used for StartTLS port: "587" # Email address that will be used as sender - from: "appcircle@yandex.com" + from: "admin@spacetech.com" # SSL configuration - Set to 'true' if the SMTP server uses SSL/TLS protocol for secure communication, typically on port 465. ssl: "false" # StartTLS configuration - Set to 'true' if the SMTP server uses StartTLS protocol, typically on port 587. tls: "true" # SMTP authentication settings auth: "true" - username: "appcircle-smtp-user" + username: "smtpUserName" password: "superSecretSmtpPassword" # Authentication configuration @@ -453,6 +479,7 @@ global: scheme: https # SMTP server configuration for sending emails (Authentication, Notifications, Testing Distribution) + # Use the same SMTP settings as specified in the `global.yaml` file of the standalone Appcircle server. mail: smtp: # SMTP server host @@ -460,7 +487,7 @@ global: # SMTP Server port, 587 typically used for StartTLS port: 587 # Email address that will be used as sender - from: appcircle@spacetech.com + from: admin@spacetech.com # SSL configuration - Set to 'true' if the SMTP server uses SSL/TLS protocol for secure communication, typically on port 465. ssl: "false" # StartTLS configuration - Set to 'true' if the SMTP server uses StartTLS protocol, typically on port 587. @@ -561,31 +588,86 @@ webeventredis: ### 3. Prepare `values.yaml` for Migration -**Make the following adjustments** to your `values.yaml` file **before deploying the Helm chart**. +**Update your `values.yaml` file** with the following configurations before deploying the Helm chart to ensure a smooth migration process. + +--- + +#### **Storage Updates** + +After [checking the data size](#3-check-the-data-size-on-the-standalone-appcircle-server) on the standalone Appcircle server, configure the storage sizes in `values.yaml` to meet or exceed your current data size requirements. Adequate storage is essential for a successful migration and seamless operation of the Appcircle server. -#### Storage Updates +For detailed instructions, refer to the [storage configuration](/self-hosted-appcircle/install-server/helm-chart/configuration/storage-configuration) page. -After [checking the data size](#3-check-the-data-size-on-the-standalone-appcircle-server) on the standalone Appcircle server, ensure that you adjust the storage size accordingly. The configured storage must meet or exceed the data size requirements to support the migration and ongoing usage of the Appcircle server. +--- -For detailed instructions on configuring storage sizes in the `values.yaml`, refer to the [storage configuration](/self-hosted-appcircle/install-server/helm-chart/configuration/storage-configuration) page. +#### **Keycloak Updates** -#### General Updates +Ensure the `organizationName` and `initialOrganizationId` in the `values.yaml` file match those in the standalone Appcircle server. -Please check the `values.yaml` below and configure your `values.yaml` according to this. +To locate these values: +1. Go to the standalone Appcircle server dashboard. +2. Switch to the root organization. +3. Open the developer tools and switch to the "Network" tab. +4. Navigate to your **Organization** page to retrieve the details. +5. You can directly see the organization name in the UI. +6. For the organization ID, filter the `userinfo` request. +7. In the response, check for `currentOrganizationId`. + + +Here’s an example configuration for `values.yaml`: ```yaml auth: - auth-keycloak: - replicas: 0 - organizationName: spacetech - initialOrganizationId: a0c5c671-35a7-47a9-a32d-eaf4edac574a + auth-keycloak: + replicas: 0 + organizationName: spacetech + initialOrganizationId: fb**************a7 +``` + +:::note +`auth-keycloak.replicas: 0`** disables Keycloak during the migration to avoid authentication conflicts. +::: +--- + +#### **MongoDB Updates** + +Set the resources preset to `"large"` for the migration phase to provide MongoDB with sufficient resources for handling larger datasets. + +Example configuration: +```yaml mongodb: - resourcesPreset: "large" + resourcesPreset: "large" ``` -- Setting `auth-keycloak.replicas` to `0` disables Keycloak authentication during migration to prevent conflicts. -- Setting `resourcesPreset` to `"large"` ensures MongoDB has sufficient resources for handling large datasets. +--- + +#### **KVS Subdomain** + +The `redis` subdomain used on the standalone Appcircle server has been updated to `kvs` in the Helm configuration for the Kubernetes deployment. + +##### If you want to update to the `kvs` subdomain: + +- **No changes are needed in the `values.yaml`** file. +- Add the **`kvs` DNS record** for the new subdomain. +- Update the **Appcircle runner configurations** to point to the new `kvs` subdomain. + +##### If you prefer to keep the `redis` subdomain (recommended): + +- Add the following configuration to the `values.yaml` file: + + ```yaml + global: + urls: + webEventRedis: + subdomain: redis + ``` + +- **No new DNS record is required**. +- **Appcircle runners do not need to be updated**. + +#### **Additional Updates** +Review the `global.yaml` file from your standalone Appcircle server for any custom configurations. Compare these settings with the Appcircle Helm chart documentation and apply them in your `values.yaml` if supported. This ensures consistency and avoids potential issues during migration. ### 4. Add the Appcircle Helm Repository @@ -604,7 +686,6 @@ In this example, we deploy the Appcircle server to a single namespace, using **` ```bash helm install appcircle-server appcircle/appcircle \ - --timeout 1200s \ -n appcircle \ -f values.yaml ``` @@ -613,18 +694,16 @@ helm install appcircle-server appcircle/appcircle \ If you need or want to change the release name, please note that it should be 18 characters or fewer. ::: -You can watch the Appcircle server installation with any Kubernetes monitoring tool. The installation process duration depends on factors such as network speed and the processing power of your Kubernetes nodes. Typically, the installation may take up to **10 to 15 minutes**. +:::caution Important Note on Helm Installation Timeout -To make sure that the Appcircle server is installed successfully, you can run the command below and wait to finish: +Since we disabled a a module before the migration, **Helm will likely wait for the module to be installed** before reporting the installation as successful. This will cause the installation to **timeout**. -```bash -kubectl wait --for=condition=ready pod \ - -l app.kubernetes.io/instance=appcircle-server \ - -n appcircle --timeout 1200s && \ - echo "Appcircle is ready to use. Happy building! " -``` +**Don't worry**, this is expected behavior. After completing the data migration steps, we will complete the Helm installation by re-enabling the job, allowing the installation to finalize successfully. +::: + +You can watch the Appcircle server installation using any Kubernetes monitoring tool. The installation process duration depends on factors such as network speed and the processing power of your Kubernetes nodes. Typically, the installation may take up to **10 to 15 minutes**. -## Migrate the Data +## Migrating the Data ### 1. Create Kubernetes Secrets @@ -636,60 +715,6 @@ Ensure you have [gathered all necessary data](#2-backup-appcircle-configuration- Some secret data, such as database passwords and Keycloak client secrets, used in the Kubernetes secrets creation below should match the data extracted from the backups of the standalone server. Ensure consistency between the backed-up values and the values used in the Kubernetes secrets to prevent connectivity and authentication issues. ::: -- **Kubernetes Namespace:** Create a namespace for Appcircle in your Kubernetes cluster: - - ```bash - kubectl create namespace appcircle - ``` - -- **Container Registry Secret:** Create the container registry secret for the Appcircle artifact registry: - -:::info -If you are using your own container registry, follow the `Custom Registry` section below. - -If your registry doesn't require authentication, you can skip this section. -::: - - - - - -- Save the `cred.json` file. - -- Create the container registry secret: - -```bash -kubectl create secret docker-registry containerregistry \ - -n appcircle \ - --docker-server='europe-west1-docker.pkg.dev' \ - --docker-username='_json_key' \ - --docker-password="$(cat cred.json)" -``` - - - - -- Update the `server`, `username`, and `password` fields for your own custom registry and create the container registry secret: - -```bash -kubectl create secret docker-registry containerregistry \ - -n appcircle \ - --docker-server='registry.spacetech.com' \ - --docker-username='yourRegistryUsername' \ - --docker-password='superSecretRegistryPassword' -``` - - - - -- **SMTP Password Secret:** Create the SMTP server password if the SMTP server that the Appcircle server will use requires authentication. - -```bash -kubectl create secret generic appcircle-server-smtp \ - -n appcircle \ - --from-file=password= -``` - - **Keycloak Clients Secret:** :::caution @@ -724,18 +749,6 @@ kubectl create secret generic appcircle-server-auth-keycloak-passwords \ --from-literal=initialPassword= \ --from-literal=adminPassword= ``` - -- **SSL Certificate Secret:** If you are using the Appcircle with HTTPS, create a secret for SSL certificates. - -```bash -kubectl create secret generic appcircle-tls-wildcard \ - -n appcircle \ - --from-file=tls.crt= \ - --from-file=tls.key= \ - --from-file=ca.crt= \ - --type=kubernetes.io/tls -``` - - **MinIO Connection Secret:** :::caution @@ -1189,12 +1202,12 @@ kubectl create secret generic appcircle-server-minio-connection \ --patch='{"stringData": { "token": "*hvs*.U5LLy********F2bOy", "unseal_keys": "dnaDMnwLuRni******M0EPJ2gAlyeHmOAy FRTs/BO606ty******1nm9pJssLZjqVULR f35t4MU6gojw******/bH92wR9t6MzzIYc" }}' ``` -## Post-Migration Steps - -After completing the migration, follow these steps to finalize and verify the setup: +## Post-installation Steps ### 1. Update the `values.yaml` +After the migration is completed, you need to enable the Keycloak module. + - **Remove Keycloak Replica Override:** Delete the `replicas: 0` setting under `auth-keycloak`. @@ -1212,18 +1225,104 @@ helm upgrade --install appcircle-server appcircle/appcircle \ -f values.yaml ``` -### 3. Update DNS Records +### 3. Update the DNS Records -- **Shift DNS to the New Cluster:** - Update the DNS records to point to the new Appcircle Kubernetes cluster. +List the Ingresses with `kubectl` to check the IP address of the Appcircle services domains. -- **Redis Subdomain Change:** - Replace the `redis` subdomain from the standalone server (e.g., `redis.appcircle.spacetech.com`) with the `kvs` subdomain for Kubernetes (e.g., `kvs.appcircle.spacetech.com`). +```bash +kubectl get ingresses -n appcircle +``` + +According to the example output below, you need to configure your DNS as follows: -- **Reference:** - For detailed instructions, see the [DNS Records Section](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/installation/kubernetes#1-add-dns-records). +```bash +NAME CLASS HOSTS ADDRESS PORTS AGE +appcircle-apigateway nginx api.appcircle.spacetech.com,auth.appcircle.spacetech.com 10.45.140.78 80,443 24m +appcircle-distribution-testerweb nginx dist.appcircle.spacetech.com 10.45.140.78 80,443 24m +appcircle-resource nginx resource.appcircle.spacetech.com 10.45.140.78 80,443 24m +appcircle-store-web nginx *.store.appcircle.spacetech.com 10.45.140.78 80,443 24m +appcircle-web-app nginx my.appcircle.spacetech.com 10.45.140.78 80,443 24m +appcircle-web-event nginx hook.appcircle.spacetech.com 10.45.140.78 80,443 24m +appcircle-webeventredis nginx kvs.appcircle.spacetech.com 10.45.140.78 80,443 24m +``` -### 4. Verification +Since you already have the DNS records for the standalone Appcircle server, all you need to do is update the DNS records to the new addresses of the Ingress objects of the Kubernetes Appcircle server. + +### 4. Login to the Appcircle Dashboard + +Check the output of the `helm install` command to see login URL, initial username and command to get initial user password. + +```bash +Self-Hosted Configuration: + +- Initial Organization Id : 8c23e250-4aa8-4ef6-888b-9514695aa1c7 +- Initial User : admin@spacetech.com +- Retrieve the initial user password by executing the following command:↴ + + kubectl get secret -n appcircle appcircle-server-auth-keycloak-passwords -ojsonpath='{.data.initialPassword}' | base64 --decode ; echo + +You can access the application dashboard at:↴ + + https://my.appcircle.spacetech.com + + +Support: +For any issues or questions, please contact the system administrator or check the application documentation. +``` + +### 5. Connecting Runners + +When you complete installation successfully by following above steps, you're ready for your first build. :tada: + +But in order to run build pipelines, you need to install and connect self-hosted runners. After completing the migration, make sure to verify that your existing self-hosted runners are properly connected to the new Kubernetes Appcircle server. You might need to update their configurations to point to the new server endpoints. + +We have dedicated section for installation and configuration of self-hosted runners. + +Follow and apply related guidelines in [here](/self-hosted-appcircle/self-hosted-runner/installation). + +Self-hosted runner section in docs, has all details about runners and their configuration. + +:::::caution + +By default, self-hosted runner package has pre-configured `ASPNETCORE_REDIS_STREAM_ENDPOINT` and `ASPNETCORE_BASE_API_URL` for Appcircle-hosted cloud. + +- `webeventredis.appcircle.io:6379,ssl=true` +- `https://api.appcircle.io/build/v1` + +:point_up: You need to change these values with your self-hosted Appcircle server's Redis and API URL. + +Assuming our sample scenario explained above, these values should be: + +- `kvs.appcircle.spacetech.com:6379,ssl=false` +- `http://api.appcircle.spacetech.com/build/v1` + +for our example configuration. + +:::info +If your Appcircle server is running with `HTTPS`, then Redis and API URL should be like this: + +- `kvs.appcircle.spacetech.com:443,ssl=true` +- `https://api.appcircle.spacetech.com/build/v1` + +::: + +:reminder_ribbon: After [download](/self-hosted-appcircle/self-hosted-runner/installation#1-download), open `appsettings.json` with a text editor and change the `ASPNETCORE_REDIS_STREAM_ENDPOINT` and the `ASPNETCORE_BASE_API_URL` values according to your configuration. + +Please note that, you should do this before [register](/self-hosted-appcircle/self-hosted-runner/installation#2-register). + +::::: + +Considering system performance, it will be good to install self-hosted runners to other machines. Self-hosted Appcircle server should run on a dedicated machine itself. + +You can install any number of runners regarding to your needs and connect them to self-hosted Appcircle server. + +### 6. Apply the Appcircle License + +When you deploy the Appcircle server using Helm, a default license is provided. You can explore the Appcircle with the default license. + +To obtain the license you purchased, please share the initial organization ID, which is printed after the `helm` deployment command, with the Appcircle team and follow the detailed instructions available in the [Appcircle License Update](/self-hosted-appcircle/install-server/helm-chart/configuration/license-configuration) section. + +### 7. Verification - Test the following functionalities and ensure all data and features are operational post-migration. - **Builds** @@ -1232,9 +1331,11 @@ helm upgrade --install appcircle-server appcircle/appcircle \ - **Testing Distribution** - **LDAP / SSO Settings** -### 5. Clean Up +### 8. Clean Up Once the migration has been confirmed as successful: - Remove old Docker containers from the standalone Appcircle server. - Delete any residual data no longer needed. + + From d2d9cc36bf709652d092d4d3525739363929214a Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Wed, 15 Jan 2025 14:15:08 +0300 Subject: [PATCH 19/40] update builds to build --- .../helm-chart/installation/docker-k8s-migration.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index ca621b9fc..85ab58ad9 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -40,6 +40,8 @@ This migration process involves downtime. To minimize disruption, **plan accordi - Notify users about the expected downtime and migration schedule. ::: +::: + ## Prerequisites To complete this guide, you must have the following: @@ -1325,7 +1327,7 @@ To obtain the license you purchased, please share the initial organization ID, w ### 7. Verification - Test the following functionalities and ensure all data and features are operational post-migration. - - **Builds** + - **Build** - **Publish** - **Enterprise App Store** - **Testing Distribution** From 25ddabbe7bcbe8f4c13575427074d43322644276 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 16 Jan 2025 13:08:40 +0300 Subject: [PATCH 20/40] fix extra caution colons --- .../installation/docker-k8s-migration.md | 56 ++++++++++--------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 85ab58ad9..2165506b0 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -37,8 +37,7 @@ This migration process involves downtime. To minimize disruption, **plan accordi - Back up all crucial data before starting the migration. - Thoroughly review each step and ensure you understand its implications. - Test the migration process in a staging or non-production environment if possible. -- Notify users about the expected downtime and migration schedule. - ::: +- Notify users about the expected downtime and migration schedule. ::: @@ -156,13 +155,12 @@ The **`kubectl`** CLI is **required**. The bastion host should meet the following requirements to facilitate the migration from the standalone Appcircle server to the Kubernetes Appcircle server: - **SSH Access**: The bastion host must have SSH access to the standalone Appcircle server. - - **Kubernetes Access**: The bastion host must be able to access the Kubernetes cluster for deploying the Helm chart and performing other tasks. - **Hardware Requirements**: - 2 CPUs - 4 GB RAM - - Sufficient disk space for migration tasks. The disk space requirement will depend on the total size of the **PostgreSQL**, **MongoDB**, and **Vault** data of the standalone Appcircle server. You can easily see the data size of the standalone Appcircle server by checking [this section](#3-check-the-data-size-on-the-standalone-appcircle-server). + - Sufficient disk space for migration tasks. The disk space requirement will depend on the total size of the **PostgreSQL**, **MongoDB**, and **Vault** data of the standalone Appcircle server. You can easily see the data size of the standalone Appcircle server by checking [this section](#3-check-the-data-size-on-the-standalone-appcircle-server). - **MinIO disk space** is not a concern, as the data is directly copied between the source and target servers without being stored on the bastion host. Ensure the bastion host has enough storage to temporarily hold any necessary migration files, but do not expect it to store the data long-term. @@ -372,16 +370,16 @@ Before proceeding with the migration, verify that the standalone Appcircle serve - **Change directory to the `appcircle-server`:** - ```bash - cd appcircle-server - ``` + ```bash + cd appcircle-server + ``` - **Check the health status of the standalone Appcircle server:** - + - ```bash - ./ac-self-hosted.sh -n spacetech check - ``` + ```bash + ./ac-self-hosted.sh -n spacetech check + ``` #### 5. Update the Standalone Appcircle Server to the Latest Version @@ -395,20 +393,21 @@ For the migration, there should be no running builds on the Appcircle during the - **Change directory to the `appcircle-server`:** - ```bash - cd appcircle-server - ``` + ```bash + cd appcircle-server + ``` - **Change directory to the `export` directory of the project:** - - ```bash - cd projects/spacetech/export - ``` + + + ```bash + cd projects/spacetech/export + ``` - **Stop the Nginx service:** - ```bash - docker compose stop nginx - ``` + ```bash + docker compose stop nginx + ``` ## Installation @@ -607,6 +606,7 @@ For detailed instructions, refer to the [storage configuration](/self-hosted-app Ensure the `organizationName` and `initialOrganizationId` in the `values.yaml` file match those in the standalone Appcircle server. To locate these values: + 1. Go to the standalone Appcircle server dashboard. 2. Switch to the root organization. 3. Open the developer tools and switch to the "Network" tab. @@ -618,6 +618,7 @@ To locate these values: Here’s an example configuration for `values.yaml`: + ```yaml auth: auth-keycloak: @@ -627,8 +628,9 @@ auth: ``` :::note -`auth-keycloak.replicas: 0`** disables Keycloak during the migration to avoid authentication conflicts. +`auth-keycloak.replicas: 0`\*\* disables Keycloak during the migration to avoid authentication conflicts. ::: + --- #### **MongoDB Updates** @@ -636,6 +638,7 @@ auth: Set the resources preset to `"large"` for the migration phase to provide MongoDB with sufficient resources for handling larger datasets. Example configuration: + ```yaml mongodb: resourcesPreset: "large" @@ -656,7 +659,7 @@ The `redis` subdomain used on the standalone Appcircle server has been updated t ##### If you prefer to keep the `redis` subdomain (recommended): - Add the following configuration to the `values.yaml` file: - + ```yaml global: urls: @@ -669,7 +672,7 @@ The `redis` subdomain used on the standalone Appcircle server has been updated t #### **Additional Updates** -Review the `global.yaml` file from your standalone Appcircle server for any custom configurations. Compare these settings with the Appcircle Helm chart documentation and apply them in your `values.yaml` if supported. This ensures consistency and avoids potential issues during migration. +Review the `global.yaml` file from your standalone Appcircle server for any custom configurations. Compare these settings with the Appcircle Helm chart documentation and apply them in your `values.yaml` if supported. This ensures consistency and avoids potential issues during migration. ### 4. Add the Appcircle Helm Repository @@ -698,7 +701,7 @@ If you need or want to change the release name, please note that it should be 18 :::caution Important Note on Helm Installation Timeout -Since we disabled a a module before the migration, **Helm will likely wait for the module to be installed** before reporting the installation as successful. This will cause the installation to **timeout**. +Since we disabled a a module before the migration, **Helm will likely wait for the module to be installed** before reporting the installation as successful. This will cause the installation to **timeout**. **Don't worry**, this is expected behavior. After completing the data migration steps, we will complete the Helm installation by re-enabling the job, allowing the installation to finalize successfully. ::: @@ -751,6 +754,7 @@ kubectl create secret generic appcircle-server-auth-keycloak-passwords \ --from-literal=initialPassword= \ --from-literal=adminPassword= ``` + - **MinIO Connection Secret:** :::caution @@ -1260,7 +1264,7 @@ Self-Hosted Configuration: - Initial Organization Id : 8c23e250-4aa8-4ef6-888b-9514695aa1c7 - Initial User : admin@spacetech.com - Retrieve the initial user password by executing the following command:↴ - + kubectl get secret -n appcircle appcircle-server-auth-keycloak-passwords -ojsonpath='{.data.initialPassword}' | base64 --decode ; echo You can access the application dashboard at:↴ From 947c1920c5588d1ca0369758928be4db8810fc0a Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 16 Jan 2025 13:28:34 +0300 Subject: [PATCH 21/40] optimize bastion host requirements --- .../installation/docker-k8s-migration.md | 39 ++++++++++++------- 1 file changed, 25 insertions(+), 14 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 2165506b0..825f888ab 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -142,28 +142,39 @@ Additionally, ensure that your Kubernetes version is 1.29.1 or later to maintain
-### 4. `kubectl` - -The **`kubectl`** CLI is **required**. - -### 5. Helm v3 - -**Helm version `3.11.0`** or later is **required**. - -### 6. Bastion Host +### 4. Bastion Host The bastion host should meet the following requirements to facilitate the migration from the standalone Appcircle server to the Kubernetes Appcircle server: -- **SSH Access**: The bastion host must have SSH access to the standalone Appcircle server. -- **Kubernetes Access**: The bastion host must be able to access the Kubernetes cluster for deploying the Helm chart and performing other tasks. - -- **Hardware Requirements**: +#### Hardware Requirements - 2 CPUs - 4 GB RAM - Sufficient disk space for migration tasks. The disk space requirement will depend on the total size of the **PostgreSQL**, **MongoDB**, and **Vault** data of the standalone Appcircle server. You can easily see the data size of the standalone Appcircle server by checking [this section](#3-check-the-data-size-on-the-standalone-appcircle-server). - **MinIO disk space** is not a concern, as the data is directly copied between the source and target servers without being stored on the bastion host. +:::info Ensure the bastion host has enough storage to temporarily hold any necessary migration files, but do not expect it to store the data long-term. +::: + +#### Software Requirements +- **Operating System**: The bastion host should be a Linux machine. You can use any popular/mainstream Linux distribution such as Ubuntu, Debian, Red Hat, CentOS, etc. +- **Required Tools**: + - `kubectl`: For managing Kubernetes clusters. + - `helm`: For deploying and managing Helm charts. + - `ssh`: For connecting to the standalone Appcircle server. + - Any other tools or dependencies needed for specific migration steps will be detailed in those steps. + +- **Network Configuration**: Ensure the bastion host can reach both the standalone Appcircle server and the Kubernetes cluster over the required network ports. + +- **Resource Accesses**: The user on the bastion host must have: + - **Standalone Appcircle server access**: The bastion host should have SSH access to the standalone Appcircle server. + - **Kubernetes Access**: The bastion host should be able to access the Kubernetes cluster API with `kubectl` for deploying Appcircle server. + +- **Tools**: The tools below are required for the migration: + - `kubectl` + - `helm` + - Additional tools needed for specific steps will be mentioned in their respective sections. Please follow the instructions in each step to ensure you have the necessary tools installed and ready to use. + ## Pre-installation Steps @@ -340,7 +351,7 @@ On the **standalone Appcircle server**, execute the following commands to back u - **Check the MinIO data size:** ```bash - echo "$APPCIRCLE_DISK_USAGE" | grep "spacetech_snsd_data" + echo "$APPCIRCLE_DISK_USAGE" | grep "spacetech_minio_snsd_data" ``` - **Check the MongoDB data size:** From cf2ae5401c106bb8f6c25201da0013e486804ea9 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 16 Jan 2025 13:30:14 +0300 Subject: [PATCH 22/40] update check the data size section --- .../installation/docker-k8s-migration.md | 49 ++++++++++++------- 1 file changed, 31 insertions(+), 18 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 825f888ab..49b9d1a26 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -147,34 +147,37 @@ Additionally, ensure that your Kubernetes version is 1.29.1 or later to maintain The bastion host should meet the following requirements to facilitate the migration from the standalone Appcircle server to the Kubernetes Appcircle server: #### Hardware Requirements - - 2 CPUs - - 4 GB RAM - - Sufficient disk space for migration tasks. The disk space requirement will depend on the total size of the **PostgreSQL**, **MongoDB**, and **Vault** data of the standalone Appcircle server. You can easily see the data size of the standalone Appcircle server by checking [this section](#3-check-the-data-size-on-the-standalone-appcircle-server). - - **MinIO disk space** is not a concern, as the data is directly copied between the source and target servers without being stored on the bastion host. + +- 2 CPUs +- 4 GB RAM +- Sufficient disk space for migration tasks. The disk space requirement will depend on the total size of the **PostgreSQL**, **MongoDB**, and **Vault** data of the standalone Appcircle server. You can easily see the data size of the standalone Appcircle server by checking [this section](#3-check-the-data-size-on-the-standalone-appcircle-server). +- **MinIO disk space** is not a concern, as the data is directly copied between the source and target servers without being stored on the bastion host. :::info Ensure the bastion host has enough storage to temporarily hold any necessary migration files, but do not expect it to store the data long-term. ::: -#### Software Requirements -- **Operating System**: The bastion host should be a Linux machine. You can use any popular/mainstream Linux distribution such as Ubuntu, Debian, Red Hat, CentOS, etc. -- **Required Tools**: - - `kubectl`: For managing Kubernetes clusters. - - `helm`: For deploying and managing Helm charts. - - `ssh`: For connecting to the standalone Appcircle server. - - Any other tools or dependencies needed for specific migration steps will be detailed in those steps. +#### Software Requirements + +- **Operating System**: The bastion host should be a Linux machine. You can use any popular/mainstream Linux distribution such as Ubuntu, Debian, Red Hat, CentOS, etc. +- **Required Tools**: + + - `kubectl`: For managing Kubernetes clusters. + - `helm`: For deploying and managing Helm charts. + - `ssh`: For connecting to the standalone Appcircle server. + - Any other tools or dependencies needed for specific migration steps will be detailed in those steps. + +- **Network Configuration**: Ensure the bastion host can reach both the standalone Appcircle server and the Kubernetes cluster over the required network ports. -- **Network Configuration**: Ensure the bastion host can reach both the standalone Appcircle server and the Kubernetes cluster over the required network ports. +- **Resource Accesses**: The user on the bastion host must have: -- **Resource Accesses**: The user on the bastion host must have: - **Standalone Appcircle server access**: The bastion host should have SSH access to the standalone Appcircle server. - **Kubernetes Access**: The bastion host should be able to access the Kubernetes cluster API with `kubectl` for deploying Appcircle server. -- **Tools**: The tools below are required for the migration: - - `kubectl` - - `helm` - - Additional tools needed for specific steps will be mentioned in their respective sections. Please follow the instructions in each step to ensure you have the necessary tools installed and ready to use. - +- **Tools**: The tools below are required for the migration: + - `kubectl` + - `helm` + - Additional tools needed for specific steps will be mentioned in their respective sections. Please follow the instructions in each step to ensure you have the necessary tools installed and ready to use. ## Pre-installation Steps @@ -342,6 +345,16 @@ On the **standalone Appcircle server**, execute the following commands to back u #### 3. Check the Data Size on the Standalone Appcircle Server +- **Log in to the standalone Appcircle server:** + +- **Change directory to the `appcircle-server`:** + + ```bash + cd appcircle-server + ``` + + + - **Get the volume sizes:** ```bash From 6f5e41aaa1a7d67ea64c600a1743ac404d091480 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 16 Jan 2025 13:52:36 +0300 Subject: [PATCH 23/40] add SSL updates --- .../installation/docker-k8s-migration.md | 228 ++++++++++-------- 1 file changed, 131 insertions(+), 97 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 49b9d1a26..3ce110217 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -223,64 +223,6 @@ If you are deploying the Appcircle server for a production environment, it is re For more information, you can check the [Production Readiness](/self-hosted-appcircle/install-server/helm-chart/configuration/production-readiness) documentation. -### 3. Create Namespace - -**Create a namespace** for the Appcircle server deployment. In this documentation, we will use `appcircle` as the example namespace. - -```bash -kubectl create namespace appcircle -``` - -### 4. Create Container Registry Secret - -By default, Appcircle uses its own image registry, which requires authentication with the `cred.json` file provided by Appcircle. - -If you are using your own container image registry to access Appcircle container images, you can either skip authentication if your registry doesn't require it or create a secret for your custom registry. - -Follow the steps below to create the registry secret in the `appcircle` namespace for pods to successfully pull images: - -:::info -If you are using your own container registry, follow the `Custom Registry` section below. - -If your registry doesn't require authentication, you can skip this section. -::: - - - - - -- Save the `cred.json` file. - -- Create the container registry secret: - -```bash -kubectl create secret docker-registry containerregistry \ - -n appcircle \ - --docker-server='europe-west1-docker.pkg.dev' \ - --docker-username='_json_key' \ - --docker-password="$(cat cred.json)" -``` - - - - -:::tip -If the `HISTCONTROL` environment variable is set to `ignoreboth`, commands with a leading space character will not be stored in the shell history. This allows you to create secrets safely without storing sensitive information in the shell history. -::: - -- Update the `server`, `username`, and `password` fields for your own custom registry and create the container registry secret: - -```bash -kubectl create secret docker-registry containerregistry \ - -n appcircle \ - --docker-server='registry.spacetech.com' \ - --docker-username='yourRegistryUsername' \ - --docker-password='superSecretRegistryPassword' -``` - - - - ### 5. Standalone Appcircle Server Steps This section outlines the essential steps to back up data from your existing Standalone Appcircle server installation and prepare your Kubernetes environment for the migration. @@ -370,7 +312,7 @@ On the **standalone Appcircle server**, execute the following commands to back u - **Check the MongoDB data size:** ```bash - echo "$APPCIRCLE_DISK_USAGE" | grep "spacetech_mongo_data" + echo "$APPCIRCLE_DISK_USAGE" | grep "spacetech_mongo_data1" ``` - **Check the PostgreSQL data size:** @@ -625,6 +567,14 @@ For detailed instructions, refer to the [storage configuration](/self-hosted-app --- +#### **SSL Updates** + +The SSL configuration of the Appcircle server Helm chart should match the SSL configuration used by the standalone Appcircle server. + +- If the standalone server is using HTTPS, configure the Helm chart for HTTPS. + - For more information about the SSL configuration, please check the [SSL configuration](/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration) page. +- If the server is running on HTTP, adjust the Helm chart configuration for HTTP. + #### **Keycloak Updates** Ensure the `organizationName` and `initialOrganizationId` in the `values.yaml` file match those in the standalone Appcircle server. @@ -744,55 +694,139 @@ Ensure you have [gathered all necessary data](#2-backup-appcircle-configuration- Some secret data, such as database passwords and Keycloak client secrets, used in the Kubernetes secrets creation below should match the data extracted from the backups of the standalone server. Ensure consistency between the backed-up values and the values used in the Kubernetes secrets to prevent connectivity and authentication issues. ::: +- **Create a namespace:** + + For the Appcircle server deployment. In this documentation, we will use `appcircle` as the example namespace. + + ```bash + kubectl create namespace appcircle + ``` + +--- + +- **Create Container Registry Secret:** + + By default, Appcircle uses its own image registry, which requires authentication with the `cred.json` file provided by Appcircle. + + If you are using your own container image registry to access Appcircle container images, you can either skip authentication if your registry doesn't require it or create a secret for your custom registry. + + Follow the steps below to create the registry secret in the `appcircle` namespace for pods to successfully pull images: + + :::info + If you are using your own container registry, follow the `Custom Registry` section below. + + If your registry doesn't require authentication, you can skip this section. + ::: + + + + + + - Save the `cred.json` file. + + - Create the container registry secret: + + ```bash + kubectl create secret docker-registry containerregistry \ + -n appcircle \ + --docker-server='europe-west1-docker.pkg.dev' \ + --docker-username='_json_key' \ + --docker-password="$(cat cred.json)" + ``` + + + + + :::tip + If the `HISTCONTROL` environment variable is set to `ignoreboth`, commands with a leading space character will not be stored in the shell history. This allows you to create secrets safely without storing sensitive information in the shell history. + ::: + + - Update the `server`, `username`, and `password` fields for your own custom registry and create the container registry secret: + + ```bash + kubectl create secret docker-registry containerregistry \ + -n appcircle \ + --docker-server='registry.spacetech.com' \ + --docker-username='yourRegistryUsername' \ + --docker-password='superSecretRegistryPassword' + ``` + + + + +--- + - **Keycloak Clients Secret:** -:::caution -The client secret values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.clients` key in the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. -::: + Create a secret with the name `${releaseName}-auth-keycloak-clients-secret` containing the relevant secret keys. -```bash -kubectl create secret generic appcircle-server-auth-keycloak-clients-secret \ - -n appcircle \ - --from-literal=appcircleWeb='dc589939-******-87b57fc1a1c7' \ - --from-literal=buildServer='307f6946-******-9d7743294f6a' \ - --from-literal=distributionAdminService='a286d519-******-227dec040f53' \ - --from-literal=distributionTesterWeb='7cc0c02a-******-5e7139d63f3c' \ - --from-literal=licenseServer='e198b11a-******-1ac96174d6f7' \ - --from-literal=publishServer='7965798e-******-0b4e8af8afed' \ - --from-literal=reportingServer='88e3abfd-******-afd2e2a1263f' \ - --from-literal=storeAdminService='f263f48f-******-588c9f55b4e3' \ - --from-literal=storeServer='08839b8d-******-aff4ecb63703' \ - --from-literal=storeWeb='9f6a406e-******-a88c17d7c2f6' \ - --from-literal=distributionServer='7cc0c02a-******-5e7139d63f3c' -``` + :::info + In the example, **`appcircle-server`** is used as the **release name**. Make sure to replace it with your actual release name if it's different. + ::: + + :::caution + The client secret values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.clients` key in the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. + ::: + + + ```bash + kubectl create secret generic appcircle-server-auth-keycloak-clients-secret \ + -n appcircle \ + --from-literal=appcircleWeb='dc589939-******-87b57fc1a1c7' \ + --from-literal=buildServer='307f6946-******-9d7743294f6a' \ + --from-literal=distributionAdminService='a286d519-******-227dec040f53' \ + --from-literal=distributionTesterWeb='7cc0c02a-******-5e7139d63f3c' \ + --from-literal=licenseServer='e198b11a-******-1ac96174d6f7' \ + --from-literal=publishServer='7965798e-******-0b4e8af8afed' \ + --from-literal=reportingServer='88e3abfd-******-afd2e2a1263f' \ + --from-literal=storeAdminService='f263f48f-******-588c9f55b4e3' \ + --from-literal=storeServer='08839b8d-******-aff4ecb63703' \ + --from-literal=storeWeb='9f6a406e-******-a88c17d7c2f6' \ + --from-literal=distributionServer='7cc0c02a-******-5e7139d63f3c' + ``` + +--- - **Keycloak Passwords Secret:** + Create a secret with the name `${releaseName}-auth-keycloak-passwords` containing the relevant secret keys. -:::caution -The Keycloak password values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.password` key for the `adminPassword` and `.keycloak.initialPassword` for the `initialPassword` in the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. -::: + :::info + In the example, **`appcircle-server`** is used as the **release name**. Make sure to replace it with your actual release name if it's different. + ::: -```bash -kubectl create secret generic appcircle-server-auth-keycloak-passwords \ - -n appcircle \ - --from-literal=initialPassword= \ - --from-literal=adminPassword= -``` + :::caution + The Keycloak password values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.password` key for the `adminPassword` and `.keycloak.initialPassword` for the `initialPassword` in the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. + ::: + + ```bash + kubectl create secret generic appcircle-server-auth-keycloak-passwords \ + -n appcircle \ + --from-literal=initialPassword= \ + --from-literal=adminPassword= + ``` + +--- - **MinIO Connection Secret:** -:::caution -The MinIO keys used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.minio.secretKey` key in the `generated-secret.yaml` file for the `accessKey` and `root-password` in the example command below. Using incorrect values will prevent Appcircle from functioning correctly. -::: + Create a secret with the name `${releaseName}-minio-connection` containing the relevant secret keys. -```bash -kubectl create secret generic appcircle-server-minio-connection \ - -n appcircle \ - --from-literal=accessKey=admin \ - --from-literal=secretKey= \ - --from-literal=root-user=admin \ - --from-literal=root-password= -``` + :::info + In the example, **`appcircle-server`** is used as the **release name**. Make sure to replace it with your actual release name if it's different. + ::: + + :::caution + The MinIO keys used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.minio.secretKey` key in the `generated-secret.yaml` file for the `accessKey` and `root-password` in the example command below. Using incorrect values will prevent Appcircle from functioning correctly. + ::: + + ```bash + kubectl create secret generic appcircle-server-minio-connection \ + -n appcircle \ + --from-literal=accessKey=admin \ + --from-literal=secretKey= \ + --from-literal=root-user=admin \ + --from-literal=root-password= + ``` ### 2. PostgreSQL Backup & Restore From 90084b1d641d6737675eadbca06f64ee2e2472ac Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 16 Jan 2025 14:08:20 +0300 Subject: [PATCH 24/40] added ca certificate danger --- .../helm-chart/configuration/ssl-configuration.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration.md index 434fb76c7..5711537fa 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration.md @@ -83,6 +83,14 @@ webeventredis: tls: true ``` +:::danger **CA Certificate Caution** +Certain SSL providers, such as Let's Encrypt, may not include the root CA certificate in their `fullchain` certificate files. In such cases, the `fullchain` file will be incomplete, as the bottom-most certificate in the chain will not be the root certificate. This can lead to compatibility issues or crashes when the certificate is used. + +To avoid such problems: +1. **Verify the Certificate Chain**: Ensure that the `fullchain` file includes all necessary certificates, starting from the server certificate up to the root certificate. +2. **Manually Append Missing Certificates**: If the root CA certificate is not included, download it from the CA's official website and append it to the `fullchain` file. +::: + ### Updating the Certificate To update the SSL certificate used on Appcircle server, perform the following steps to update the Helm chart and restart the required services: From 76873daa6d868ae22cb778865689010c98741c95 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 16 Jan 2025 14:49:31 +0300 Subject: [PATCH 25/40] add info for external stateful apps --- .../installation/docker-k8s-migration.md | 121 +++++++++++++----- 1 file changed, 87 insertions(+), 34 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 3ce110217..bf0d1c2c1 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -41,6 +41,14 @@ This migration process involves downtime. To minimize disruption, **plan accordi ::: +:::info +In this documentation, we will migrate from a **standalone Appcircle server** to a **Kubernetes-based Appcircle server** using the **internal stateful applications** (PostgreSQL, MongoDB, MinIO, Vault) provided by the Appcircle Helm chart. + +If you choose to use **external stateful services**, you will need to adapt certain migration commands to fit your **custom environment**. Specific commands requiring modifications for external deployments are highlighted in the relevant sections of this documentation. + +In the case of using **external stateful services**, the **bastion host requirements** should be adjusted to meet your **specific setup**. For example, the **storage** and **access requirements** for the external databases and services will need to be accounted for during the migration. Please ensure that your **bastion host** is configured with appropriate resources and network access to support these **external services**. +::: + ## Prerequisites To complete this guide, you must have the following: @@ -223,7 +231,7 @@ If you are deploying the Appcircle server for a production environment, it is re For more information, you can check the [Production Readiness](/self-hosted-appcircle/install-server/helm-chart/configuration/production-readiness) documentation. -### 5. Standalone Appcircle Server Steps +### 3. Standalone Appcircle Server Steps This section outlines the essential steps to back up data from your existing Standalone Appcircle server installation and prepare your Kubernetes environment for the migration. @@ -245,7 +253,7 @@ Before starting, create a full backup of your Appcircle server. Options include: On your **bastion host**, create a directory to store all migration files: ```bash -mkdir appcircle-k8s-migration && cd appcircle-k8s-migration +mkdir appcircle-k8s-migration ``` #### 2. Backup Appcircle Configuration Data @@ -851,37 +859,48 @@ Some secret data, such as database passwords and Keycloak client secrets, used i #### Bastion Host -1. **Copy the PostgreSQL Data to Bastion Host**: Copy the dumped PostgreSQL data from the Appcircle server to the bastion host. +1. **Log in to the bastion host.** + +2. **Change directory to the temporary directory that was created for storing the standalone Appcircle server files:** + ```bash + cd appcircle-k8s-migration + ``` + +3. **Copy the PostgreSQL Data to Bastion Host**: Copy the dumped PostgreSQL data from the Appcircle server to the bastion host. ```bash scp standalone-appcircle-server/app/appcircle-server/projects/spacetech/export/mongo-backup.gz . ``` -2. **Get PostgreSQL Password:** +:::info +If you have used an **external PostgreSQL service** instead of the one provided with the Appcircle Helm chart, please adjust the commands below for your **specific use-case**. +::: + +4. **Get PostgreSQL Password:** ```bash kubectl get secret -n appcircle appcircle-server-auth-postgresql -ojsonpath='{.data.password}' | base64 -d ``` -3. **Get the PostgreSQL pod name:** +5. **Get the PostgreSQL pod name:** ```bash kubectl get pods -n appcircle | grep postgres ``` -4. **Install PostgreSQL tools:** +6. **Install PostgreSQL tools:** ```bash brew install postgresql ``` -5. **Start Port Forwarding:** +7. **Start Port Forwarding:** ```bash kubectl port-forward appcircle-server-auth-postgresql-0 5432:5432 -n appcircle ``` -6. **Restore the Database:** +8. **Restore the Database:** ```bash pg_restore -h localhost -p 5432 -U keycloak -d keycloak ~/appcircle-k8s-migration/pgdump.backup ``` @@ -969,27 +988,39 @@ Some secret data, such as database passwords and Keycloak client secrets, used i #### Bastion Host -1. **Copy the file from the standalone Appcircle server to the bastion host:** +1. **Log in to the bastion host.** + +2. **Change directory to the temporary directory that was created for storing the standalone Appcircle server files:** + + ```bash + cd appcircle-k8s-migration + ``` + +3. **Copy the file from the standalone Appcircle server to the bastion host:** ```bash scp standalone-appcircle-server/app/appcircle-server/projects/spacetech/export/mongo-backup.gz . ``` -2. **Install MongoDB Database Tools:** +:::info +If you have used an **external MongoDB service** instead of the one provided with the Appcircle Helm chart, please adjust the commands below for your **specific use-case**. +::: + +4. **Install MongoDB Database Tools:** To install MongoDB Database Tools, please check the [official MongoDB documentation](https://www.mongodb.com/docs/database-tools/installation/installation/#installation). -3. **Get the MongoDB root password of the K8s installation:** +5. **Get the MongoDB root password of the K8s installation:** ```bash kubectl get secret -n appcircle appcircle-server-mongodb -o jsonpath='{.data.mongodb-root-password}' | base64 -d ``` -4. **Start port forwarding:** +6. **Start port forwarding:** ```bash kubectl port-forward appcircle-server-mongodb-0 27017:27017 -n appcircle ``` -5. **Restore the dumped MongoDB:** +7. **Restore the dumped MongoDB:** ```bash mongorestore --uri="mongodb://root:@localhost:27017/?authSource=admin" --gzip --archive=./mongo-backup.gz ``` @@ -1020,9 +1051,19 @@ Some secret data, such as database passwords and Keycloak client secrets, used i #### Bastion Host -1. **Log in to the bastion:** +1. **Log in to the bastion host.** + +2. **Change directory to the temporary directory that was created for storing the standalone Appcircle server files:** + + ```bash + cd appcircle-k8s-migration + ``` + +:::info +If you have used an **external MinIO service** instead of the one provided with the Appcircle Helm chart, please adjust the commands below for your **specific use-case**. +::: -2. **Get the Kubernetes MinIO access and secret keys:** +3. **Get the Kubernetes MinIO access and secret keys:** ```bash kubectl get secret -n appcircle appcircle-server-minio-connection -ojsonpath='{.data.accessKey}' | base64 -d && \ @@ -1030,13 +1071,13 @@ Some secret data, such as database passwords and Keycloak client secrets, used i kubectl get secret -n appcircle appcircle-server-minio-connection -ojsonpath='{.data.secretKey}' | base64 -d ``` -3. **Get the MinIO service name:** +4. **Get the MinIO service name:** ```bash kubectl get services -n appcircle | grep minio ``` -4. **Change MinIO service to NodePort for temporary:** +5. **Change MinIO service to NodePort for temporary:** :::info We recommend opening the MinIO service to the external network temporarily instead of using `kubectl port-forward` since you might have problems while transferring large files over port forwarding of the `kubectl`. @@ -1048,7 +1089,7 @@ Some secret data, such as database passwords and Keycloak client secrets, used i kubectl patch service appcircle-server-minio -n appcircle --type='json' -p='[{"op": "replace", "path": "/spec/type", "value": "NodePort"}, {"op": "add", "path": "/spec/ports/0/nodePort", "value": 30534}, {"op": "add", "path": "/spec/ports/1/nodePort", "value": 32761}]' ``` -5. **Install `rclone` tool:** +6. **Install `rclone` tool:** :::info We recommended using `rclone` tool instead of `mc`. @@ -1056,7 +1097,7 @@ Some secret data, such as database passwords and Keycloak client secrets, used i To install `rclone`, please check the [official rclone documentation](https://rclone.org/install/). -6. **Add Rclone Configuration for Standalone Server:** +7. **Add Rclone Configuration for Standalone Server:** To configure Rclone for the standalone Appcircle server, follow these steps: @@ -1085,7 +1126,7 @@ Some secret data, such as database passwords and Keycloak client secrets, used i Edit advanced config? (y/n): n # Skip advanced configuration ``` -7. **Add Rclone config for Kubernetes Appcircle server:** +8. **Add Rclone config for Kubernetes Appcircle server:** To configure `rclone` for the Kubernetes Appcircle server, follow these steps: @@ -1114,7 +1155,7 @@ Some secret data, such as database passwords and Keycloak client secrets, used i Edit advanced config? (y/n): n # Skip advanced configuration ``` -8. **Start copying files:** +9. **Start copying files:** ```bash rclone copy --progress --checksum --update ac-standalone: ac-k8s: @@ -1192,43 +1233,55 @@ Some secret data, such as database passwords and Keycloak client secrets, used i #### Bastion Host -1. **Copy the vault data tar ball to the bastion host:** +1. **Log in to the bastion host.** + +2. **Change directory to the temporary directory that was created for storing the standalone Appcircle server files:** + + ```bash + cd appcircle-k8s-migration + ``` + +3. **Copy the vault data tar ball to the bastion host:** ```bash scp standalone-appcircle-server/app/appcircle-server/vaultd.tar.gz . ``` -2. **Get the Vault statefulset name:** +:::info +If you have used an **external Vault service** instead of the one provided with the Appcircle Helm chart, please adjust the commands below for your **specific use-case**. +::: + +4. **Get the Vault statefulset name:** ```bash kubectl get statefulsets -n appcircle | grep vault ``` -3. **Edit the vault `statefulset` for safe operations:** +4. **Edit the vault `statefulset` for safe operations:** ```bash kubectl patch statefulset -n appcircle appcircle-server-vault -p '{"spec": {"template": {"spec":{"containers":[{"name":"vault","command": ["sh", "-c", "tail -f /dev/null" ], "args": null, "readinessProbe": null, "lifecycle": null }]}}}}' ``` -4. **Delete the pod for it to be re-created:** +5. **Delete the pod for it to be re-created:** ```bash kubectl delete pod appcircle-server-vault-0 -n appcircle ``` -5. **Copy the vault data to the target pod:** +6. **Copy the vault data to the target pod:** ```bash kubectl cp "./vaultd.tar.gz" "appcircle-server-vault-0:/vault/data/vaultd.tar.gz" -n appcircle ``` -6. **Open shell in the vault container:** +7. **Open shell in the vault container:** ```bash kubectl exec -it appcircle-server-vault-0 -- bash ``` -7. **Run the following commands in the shell:** +8. **Run the following commands in the shell:** ```bash cd /vault/data @@ -1236,15 +1289,15 @@ Some secret data, such as database passwords and Keycloak client secrets, used i /usr/local/bin/docker-entrypoint.sh vault server -config=/vault/config/extraconfig-from-values.hcl ``` -8. **Don't close the upper terminal until the process finishes:** +9. **Don't close the upper terminal until the process finishes:** -9. **Open a new terminal in the vault container:** +10. **Open a new terminal in the vault container:** ```bash kubectl exec -it appcircle-server-vault-0 -- bash ``` -10. **Unseal the vault with the saved keys from the steps above:** +11. **Unseal the vault with the saved keys from the steps above:** ```bash vault operator unseal dnaDMnwLuRni******M0EPJ2gAlyeHmOAy @@ -1252,15 +1305,15 @@ Some secret data, such as database passwords and Keycloak client secrets, used i vault operator unseal f35t4MU6gojw******/bH92wR9t6MzzIYc ``` -11. **Delete the vault data tar ball:** +12. **Delete the vault data tar ball:** ```bash rm /vault/data/vaultd.tar.gz ``` -12. **Exit from the first and second vault terminal:** +13. **Exit from the first and second vault terminal:** -13. **Edit the secret with old unseal keys:** +14. **Edit the secret with old unseal keys:** ```bash kubectl patch secret appcircle-server-vault-seal -n appcircle \ --patch='{"stringData": { "token": "*hvs*.U5LLy********F2bOy", "unseal_keys": "dnaDMnwLuRni******M0EPJ2gAlyeHmOAy FRTs/BO606ty******1nm9pJssLZjqVULR f35t4MU6gojw******/bH92wR9t6MzzIYc" }}' From 3993091ad11dfdc4d66a9487a07c2f9d699fcf23 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 16 Jan 2025 15:05:25 +0300 Subject: [PATCH 26/40] added check version --- .../installation/docker-k8s-migration.md | 44 ++++++++++++++++++- 1 file changed, 42 insertions(+), 2 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index bf0d1c2c1..1e48e5fa4 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -355,9 +355,38 @@ Before proceeding with the migration, verify that the standalone Appcircle serve ./ac-self-hosted.sh -n spacetech check ``` -#### 5. Update the Standalone Appcircle Server to the Latest Version +#### 5. Check the Standalone Appcircle Server Version -Before migrating to Kubernetes Appcircle server, please [update the standalone Appcircle server](https://docs.appcircle.io/self-hosted-appcircle/install-server/linux-package/update) to the latest version. +Before the migration, you should check the version of the Appcircle server and take the following actions: + +- **Check the latest standalone Appcircle server version:** + + Please check the standalone Appcircle server [version history](https://docs.appcircle.io/self-hosted-appcircle/install-server/linux-package/update#version-history) to learn the latest version. + +- **Log in to the standalone Appcircle server:** + +- **Change directory to the `appcircle-server`:** + + ```bash + cd appcircle-server + ``` + +- **Check the Appcircle server version:** + + + + ```bash + ./ac-self-hosted.sh -n spacetech version + ``` + - If the version of the standalone Appcircle server is the latest: + - You can proceed with using the latest Appcircle Helm chart. + + - If the Appcircle server version is greater than or equal to `3.23.2`: + - You may opt to install a Helm chart version that corresponds to your specific standalone Appcircle server version. + - Please check the [version history of the Helm chart](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/upgrades#version-history) and use the latest Helm chart version for that version. + + - If the Appcircle server version is earlier than `3.23.2`: + - Update the standalone Appcircle server to at least version `3.23.2` prior to initiating the migration. #### 6. Stop the Standalone Appcircle Server Requests. @@ -677,6 +706,17 @@ helm install appcircle-server appcircle/appcircle \ -f values.yaml ``` +:::tip +To install specific version of the Appcircle Helm chart, you can use the example command below: + +```bash +helm install appcircle-server appcircle/appcircle \ + -n appcircle \ + -f values.yaml + --version 0.1.1 +``` +::: + :::warning If you need or want to change the release name, please note that it should be 18 characters or fewer. ::: From b56e561b84bacd602c2ade3b023674ed3ed4be2c Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Wed, 5 Feb 2025 10:24:35 +0300 Subject: [PATCH 27/40] add namespace to the td custom domain command --- .../helm-chart/configuration/advanced-configuration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/advanced-configuration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/advanced-configuration.md index e24f123e2..498c9e47b 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/advanced-configuration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/advanced-configuration.md @@ -44,10 +44,11 @@ After updating the `values.yaml` file, create a TLS secret for the custom domain - The certificate (`cert`) should be in **PEM format** and it's recommended to include the leaf (app), intermediate, and root (CA) certificates to form a **full-chain** certificate. - The private key (`key`) **should not be password-protected**. - ::: +::: ```bash kubectl create secret tls k8s-dist-spacetech-com-tls \ +-n appcircle \ --cert=fullchain.crt \ --key=private.key ``` From e5a657d94d6704d3add0824a10d6e788512b10b2 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Wed, 5 Feb 2025 12:01:53 +0300 Subject: [PATCH 28/40] add general info --- .../installation/docker-k8s-migration.md | 103 +++++++++++------- 1 file changed, 62 insertions(+), 41 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 1e48e5fa4..38701dfcf 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -386,7 +386,7 @@ Before the migration, you should check the version of the Appcircle server and t - Please check the [version history of the Helm chart](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/upgrades#version-history) and use the latest Helm chart version for that version. - If the Appcircle server version is earlier than `3.23.2`: - - Update the standalone Appcircle server to at least version `3.23.2` prior to initiating the migration. + - [Update the standalone Appcircle server](/self-hosted-appcircle/install-server/linux-package/update.md) to at least version `3.23.2` prior to initiating the migration. #### 6. Stop the Standalone Appcircle Server Requests. @@ -438,6 +438,7 @@ Please **review the comments for the `values.yaml`** below. If the values provid global: urls: # Main domain configuration - All Appcircle services will be subdomains of this domain + # Use the same domain as specified in the `global.yaml` file of the standalone Appcircle server. domainName: .appcircle.spacetech.com # SMTP server configuration for sending emails (Authentication, Notifications, Testing Distribution) # Use the same SMTP settings as specified in the `global.yaml` file of the standalone Appcircle server. @@ -463,6 +464,8 @@ auth: auth-keycloak: # Initial admin user email for Appcircle server initialUsername: "admin@spacetech.com" +signingidentity: + vaultServicePrefix: signing ```
@@ -478,8 +481,10 @@ auth: global: urls: # Main domain configuration - All Appcircle services will be subdomains of this domain + # Use the same domain as specified in the `global.yaml` file of the standalone Appcircle server. domainName: .appcircle.spacetech.com # Protocol to be used for connections + # Use the same scheme settings as specified in the `global.yaml` file of the standalone Appcircle server. scheme: https # SMTP server configuration for sending emails (Authentication, Notifications, Testing Distribution) @@ -579,6 +584,9 @@ webeventredis: ingress: enabled: true tls: true + +signingidentity: + vaultServicePrefix: signing ``` @@ -728,7 +736,17 @@ Since we disabled a a module before the migration, **Helm will likely wait for t **Don't worry**, this is expected behavior. After completing the data migration steps, we will complete the Helm installation by re-enabling the job, allowing the installation to finalize successfully. ::: -You can watch the Appcircle server installation using any Kubernetes monitoring tool. The installation process duration depends on factors such as network speed and the processing power of your Kubernetes nodes. Typically, the installation may take up to **10 to 15 minutes**. +You can watch the Appcircle server installation using any Kubernetes monitoring tool. The installation process duration depends on factors such as network speed and the processing power of your Kubernetes nodes. + +To make sure that the stateful apps are ready for migration, you can run the command below and wait for `The databases are ready for migration steps.` output. + +```bash +kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=auth-postgresql' --timeout=300s && \ +kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=mongodb' --timeout=300s && \ +kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=minio' --timeout=300s && \ +kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=vault' --timeout=300s && \ +echo "The databases are ready for migration steps." +``` ## Migrating the Data @@ -908,10 +926,6 @@ Some secret data, such as database passwords and Keycloak client secrets, used i 3. **Copy the PostgreSQL Data to Bastion Host**: Copy the dumped PostgreSQL data from the Appcircle server to the bastion host. - ```bash - scp standalone-appcircle-server/app/appcircle-server/projects/spacetech/export/mongo-backup.gz . - ``` - :::info If you have used an **external PostgreSQL service** instead of the one provided with the Appcircle Helm chart, please adjust the commands below for your **specific use-case**. ::: @@ -928,11 +942,19 @@ If you have used an **external PostgreSQL service** instead of the one provided kubectl get pods -n appcircle | grep postgres ``` -6. **Install PostgreSQL tools:** +6. **Install PostgreSQL client tools:** + + To install PostgreSQL client tools, please check the [official PostgreSQL documentation](https://www.postgresql.org/download/). + + :::info + Instead of installing the latest `postgresql-client-*` version, please install the `postgresql-client-14` package. + + An example command should be like the one below: ```bash - brew install postgresql + sudo apt install postgresql-client-14 ``` + ::: 7. **Start Port Forwarding:** @@ -975,10 +997,11 @@ If you have used an **external PostgreSQL service** instead of the one provided - "36300:36300" ``` - - Restart the services. + - Restart the `mongo_1` service. ```bash - ./ac-self-hosted -n spacetech up + cd projects/aselsan2/export/ && \ + docker compose up mongo_1 --no-deps --force-recreate -d ``` 3. **Install the `mongosh` tool.** @@ -1003,25 +1026,30 @@ If you have used an **external PostgreSQL service** instead of the one provided db.createUser({user: "backup",pwd: "backup",roles: [{ role: "root", db: "admin"}]}) ``` -7. **Get the MongoDB container name:** +7. **Exit from the Mongo Shell:** + + ```mongosh + exit + ``` + +8. **Get the MongoDB container name:** ```bash docker ps | grep mongo_1 ``` -8. **Get the MongoDB connection string:** +9. **Get the MongoDB connection string:** ```bash cat projects/spacetech/export/publish/default.env | grep "CUSTOMCONNSTR_PUBLISH_DB_CONNECTION_STRING" ``` 9. **Dump the MongoDB:** - ```bash docker exec -it spacetech-mongo_1-1 mongodump --uri="mongodb://backup:backup@mongo_1:36300,mongo_2:36301,mongo_3:36302/?replicaSet=rs&authSource=admin" --gzip --archive=/mongo-backup.gz ``` -10. **Copy the dumped DB file from out of the container to the host machine:** +9. **Copy the dumped DB file from out of the container to the host machine:** ```bash docker cp spacetech-mongo_1-1:/mongo-backup.gz . ``` @@ -1038,13 +1066,9 @@ If you have used an **external PostgreSQL service** instead of the one provided 3. **Copy the file from the standalone Appcircle server to the bastion host:** - ```bash - scp standalone-appcircle-server/app/appcircle-server/projects/spacetech/export/mongo-backup.gz . - ``` - -:::info -If you have used an **external MongoDB service** instead of the one provided with the Appcircle Helm chart, please adjust the commands below for your **specific use-case**. -::: + :::info + If you have used an **external MongoDB service** instead of the one provided with the Appcircle Helm chart, please adjust the commands below for your **specific use-case**. + ::: 4. **Install MongoDB Database Tools:** @@ -1117,16 +1141,9 @@ If you have used an **external MinIO service** instead of the one provided with kubectl get services -n appcircle | grep minio ``` -5. **Change MinIO service to NodePort for temporary:** - - :::info - We recommend opening the MinIO service to the external network temporarily instead of using `kubectl port-forward` since you might have problems while transferring large files over port forwarding of the `kubectl`. - - Note that this doesn't make the MinIO data public as long as you keep the MinIO password secret. - ::: - +6. **Start port forwarding:** ```bash - kubectl patch service appcircle-server-minio -n appcircle --type='json' -p='[{"op": "replace", "path": "/spec/type", "value": "NodePort"}, {"op": "add", "path": "/spec/ports/0/nodePort", "value": 30534}, {"op": "add", "path": "/spec/ports/1/nodePort", "value": 32761}]' + kubectl port-forward service/appcircle-server-minio 9000:9000 -n appcircle ``` 6. **Install `rclone` tool:** @@ -1187,7 +1204,7 @@ If you have used an **external MinIO service** instead of the one provided with access_key_id> # Enter the standalone Appcircle server's access key secret_access_key> # Enter the standalone Appcircle server's secret access key region> # Leave this empty - endpoint> # Provide the standalone Appcircle server's IP and MinIO port. Example: http://192.168.1.220:9040 + endpoint> # Provide the standalone Appcircle server's IP and MinIO port. Example: http://127.0.0.1:9000 location_constraint: # Leave this empty acl: # Leave this empty server_side_encryption: # Leave this empty @@ -1283,10 +1300,6 @@ If you have used an **external MinIO service** instead of the one provided with 3. **Copy the vault data tar ball to the bastion host:** - ```bash - scp standalone-appcircle-server/app/appcircle-server/vaultd.tar.gz . - ``` - :::info If you have used an **external Vault service** instead of the one provided with the Appcircle Helm chart, please adjust the commands below for your **specific use-case**. ::: @@ -1382,7 +1395,15 @@ helm upgrade --install appcircle-server appcircle/appcircle \ -f values.yaml ``` -### 3. Update the DNS Records +### 3. Restart All the Deployments + +Restart all the Appcircle server deployments to make sure every service is restarting with the up-to-date configurations. + +```bash +kubectl rollout restart deployment -n appcircle +``` + +### 4. Update the DNS Records List the Ingresses with `kubectl` to check the IP address of the Appcircle services domains. @@ -1405,7 +1426,7 @@ appcircle-webeventredis nginx kvs.appcircle.spacetech.com Since you already have the DNS records for the standalone Appcircle server, all you need to do is update the DNS records to the new addresses of the Ingress objects of the Kubernetes Appcircle server. -### 4. Login to the Appcircle Dashboard +### 5. Login to the Appcircle Dashboard Check the output of the `helm install` command to see login URL, initial username and command to get initial user password. @@ -1427,7 +1448,7 @@ Support: For any issues or questions, please contact the system administrator or check the application documentation. ``` -### 5. Connecting Runners +### 6. Connecting Runners When you complete installation successfully by following above steps, you're ready for your first build. :tada: @@ -1473,13 +1494,13 @@ Considering system performance, it will be good to install self-hosted runners t You can install any number of runners regarding to your needs and connect them to self-hosted Appcircle server. -### 6. Apply the Appcircle License +### 7. Apply the Appcircle License When you deploy the Appcircle server using Helm, a default license is provided. You can explore the Appcircle with the default license. To obtain the license you purchased, please share the initial organization ID, which is printed after the `helm` deployment command, with the Appcircle team and follow the detailed instructions available in the [Appcircle License Update](/self-hosted-appcircle/install-server/helm-chart/configuration/license-configuration) section. -### 7. Verification +### 8. Verification - Test the following functionalities and ensure all data and features are operational post-migration. - **Build** @@ -1488,7 +1509,7 @@ To obtain the license you purchased, please share the initial organization ID, w - **Testing Distribution** - **LDAP / SSO Settings** -### 8. Clean Up +### 9. Clean Up Once the migration has been confirmed as successful: From 9c065606366e93ebd2ddf0be1a0acd128345ead5 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Wed, 5 Feb 2025 16:43:35 +0300 Subject: [PATCH 29/40] add SSL tip box --- .../installation/docker-k8s-migration.md | 132 +++++++++--------- 1 file changed, 66 insertions(+), 66 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 38701dfcf..8e0f38c59 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -82,6 +82,10 @@ By default, Appcircle uses seven subdomains. These subdomains are: If the **standalone Appcircle server** is already using **HTTPS**, you **should provide an SSL certificate** for the Appcircle server Kubernetes deployment. +:::tip +You can reuse the SSL certificates from your standalone Appcircle server for the Kubernetes deployment. These certificates can be found in your standalone server's `global.yaml` or `user-secret` file. This will ensure consistency and avoid the need to generate new certificates. +::: + If the **standalone Appcircle server** uses **HTTP**, you can **skip configuring an SSL certificate**.
@@ -182,11 +186,6 @@ Ensure the bastion host has enough storage to temporarily hold any necessary mig - **Standalone Appcircle server access**: The bastion host should have SSH access to the standalone Appcircle server. - **Kubernetes Access**: The bastion host should be able to access the Kubernetes cluster API with `kubectl` for deploying Appcircle server. -- **Tools**: The tools below are required for the migration: - - `kubectl` - - `helm` - - Additional tools needed for specific steps will be mentioned in their respective sections. Please follow the instructions in each step to ensure you have the necessary tools installed and ready to use. - ## Pre-installation Steps ### 1. Ingress Controller @@ -693,64 +692,8 @@ The `redis` subdomain used on the standalone Appcircle server has been updated t Review the `global.yaml` file from your standalone Appcircle server for any custom configurations. Compare these settings with the Appcircle Helm chart documentation and apply them in your `values.yaml` if supported. This ensures consistency and avoids potential issues during migration. -### 4. Add the Appcircle Helm Repository -**Add the Appcircle Helm repository** to the configuration of Helm: - -```bash -helm repo add appcircle https://helm-package.appcircle.io && \ -helm repo update -``` - -### 5. Install the Appcircle Server - -**Run the following Helm command** to install the Appcircle server chart. - -In this example, we deploy the Appcircle server to a single namespace, using **`appcircle`** as the **namespace** and **`appcircle-server`** as the Helm **release name**. - -```bash -helm install appcircle-server appcircle/appcircle \ - -n appcircle \ - -f values.yaml -``` - -:::tip -To install specific version of the Appcircle Helm chart, you can use the example command below: - -```bash -helm install appcircle-server appcircle/appcircle \ - -n appcircle \ - -f values.yaml - --version 0.1.1 -``` -::: - -:::warning -If you need or want to change the release name, please note that it should be 18 characters or fewer. -::: - -:::caution Important Note on Helm Installation Timeout - -Since we disabled a a module before the migration, **Helm will likely wait for the module to be installed** before reporting the installation as successful. This will cause the installation to **timeout**. - -**Don't worry**, this is expected behavior. After completing the data migration steps, we will complete the Helm installation by re-enabling the job, allowing the installation to finalize successfully. -::: - -You can watch the Appcircle server installation using any Kubernetes monitoring tool. The installation process duration depends on factors such as network speed and the processing power of your Kubernetes nodes. - -To make sure that the stateful apps are ready for migration, you can run the command below and wait for `The databases are ready for migration steps.` output. - -```bash -kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=auth-postgresql' --timeout=300s && \ -kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=mongodb' --timeout=300s && \ -kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=minio' --timeout=300s && \ -kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=vault' --timeout=300s && \ -echo "The databases are ready for migration steps." -``` - -## Migrating the Data - -### 1. Create Kubernetes Secrets +### 4. Create Kubernetes Secrets This section details the creation of Kubernetes secrets required for Appcircle to function correctly. These secrets store sensitive information such as passwords and certificates, securely injecting them into your Appcircle deployment. @@ -894,7 +837,64 @@ Some secret data, such as database passwords and Keycloak client secrets, used i --from-literal=root-password= ``` -### 2. PostgreSQL Backup & Restore +### 5. Add the Appcircle Helm Repository + +**Add the Appcircle Helm repository** to the configuration of Helm: + +```bash +helm repo add appcircle https://helm-package.appcircle.io && \ +helm repo update +``` + +### 6. Install the Appcircle Server + +**Run the following Helm command** to install the Appcircle server chart. + +In this example, we deploy the Appcircle server to a single namespace, using **`appcircle`** as the **namespace** and **`appcircle-server`** as the Helm **release name**. + +```bash +helm install appcircle-server appcircle/appcircle \ + -n appcircle \ + -f values.yaml +``` + +:::tip +To install specific version of the Appcircle Helm chart, you can use the example command below: + +```bash +helm install appcircle-server appcircle/appcircle \ + -n appcircle \ + -f values.yaml + --version 0.1.1 +``` +::: + +:::warning +If you need or want to change the release name, please note that it should be 18 characters or fewer. +::: + +:::caution Important Note on Helm Installation Timeout + +Since we disabled a a module before the migration, **Helm will likely wait for the module to be installed** before reporting the installation as successful. This will cause the installation to **timeout**. + +**Don't worry**, this is expected behavior. After completing the data migration steps, we will complete the Helm installation by re-enabling the job, allowing the installation to finalize successfully. +::: + +You can watch the Appcircle server installation using any Kubernetes monitoring tool. The installation process duration depends on factors such as network speed and the processing power of your Kubernetes nodes. + +To make sure that the stateful apps are ready for migration, you can run the command below and wait for `The databases are ready for migration steps.` output. + +```bash +kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=auth-postgresql' --timeout=300s && \ +kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=mongodb' --timeout=300s && \ +kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=minio' --timeout=300s && \ +kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=vault' --timeout=300s && \ +echo "The databases are ready for migration steps." +``` + +## Migrating the Data + +### 1. PostgreSQL Backup & Restore #### Standalone Appcircle Server @@ -967,7 +967,7 @@ If you have used an **external PostgreSQL service** instead of the one provided pg_restore -h localhost -p 5432 -U keycloak -d keycloak ~/appcircle-k8s-migration/pgdump.backup ``` -### 3. MongoDB Backup & Restore +### 2. MongoDB Backup & Restore #### Standalone Appcircle Server @@ -1089,7 +1089,7 @@ If you have used an **external PostgreSQL service** instead of the one provided mongorestore --uri="mongodb://root:@localhost:27017/?authSource=admin" --gzip --archive=./mongo-backup.gz ``` -### 4. MinIO Mirror +### 3. MinIO Mirror #### Standalone Appcircle Server @@ -1218,7 +1218,7 @@ If you have used an **external MinIO service** instead of the one provided with rclone copy --progress --checksum --update ac-standalone: ac-k8s: ``` -### 5. Vault Backup & Restore +### 4. Vault Backup & Restore #### Standalone Server Steps From 4b3893a0b2bbdb830e249791c315633375b15d70 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 6 Feb 2025 12:09:44 +0300 Subject: [PATCH 30/40] update organization name & id --- .../installation/docker-k8s-migration.md | 39 ++++++++++++++----- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 8e0f38c59..5b94722bb 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -387,7 +387,21 @@ Before the migration, you should check the version of the Appcircle server and t - If the Appcircle server version is earlier than `3.23.2`: - [Update the standalone Appcircle server](/self-hosted-appcircle/install-server/linux-package/update.md) to at least version `3.23.2` prior to initiating the migration. -#### 6. Stop the Standalone Appcircle Server Requests. +#### 6. Find the Organization Name + +To migrate the Appcircle server data, you should find the name of the current organization. + +To find the organization name: + +1. Go to the standalone Appcircle server dashboard. +2. Switch to the root organization. +3. Navigate to your **Organization** page to retrieve the details. +4. You can directly see the organization name in the UI. +5. Save the organization name to use on the next steps. + + + +#### 7. Stop the Standalone Appcircle Server Requests. For the migration, there should be no running builds on the Appcircle during the migration. Also prevent external requests while keeping the server healthy by stopping the Nginx service. @@ -623,17 +637,22 @@ The SSL configuration of the Appcircle server Helm chart should match the SSL co Ensure the `organizationName` and `initialOrganizationId` in the `values.yaml` file match those in the standalone Appcircle server. -To locate these values: +To locate the `initialOrganizationId`: -1. Go to the standalone Appcircle server dashboard. -2. Switch to the root organization. -3. Open the developer tools and switch to the "Network" tab. -4. Navigate to your **Organization** page to retrieve the details. -5. You can directly see the organization name in the UI. -6. For the organization ID, filter the `userinfo` request. -7. In the response, check for `currentOrganizationId`. +1. Login to the **bastion host**. +2. Change directory to the location where you have saved the backup files. + +```bash +cd appcircle-k8s-migration +``` + +3. Check the `initialOrganizationId` value. + +```bash +grep 'initialOrganizationId' generated-secret.yaml +``` - +4. Also get the organization name you have checked from the [step above](#6-find-the-organization-name). Here’s an example configuration for `values.yaml`: From f930a0f44ac5d01033cd1ac53cc78cea97a04d10 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 6 Feb 2025 12:10:25 +0300 Subject: [PATCH 31/40] add namespace to kubectl wait --- .../helm-chart/installation/docker-k8s-migration.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 5b94722bb..c024d71d9 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -904,10 +904,10 @@ You can watch the Appcircle server installation using any Kubernetes monitoring To make sure that the stateful apps are ready for migration, you can run the command below and wait for `The databases are ready for migration steps.` output. ```bash -kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=auth-postgresql' --timeout=300s && \ -kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=mongodb' --timeout=300s && \ -kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=minio' --timeout=300s && \ -kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=vault' --timeout=300s && \ +kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=auth-postgresql' -n appcircle --timeout=300s && \ +kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=mongodb' -n appcircle --timeout=300s && \ +kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=minio' -n appcircle --timeout=300s && \ +kubectl wait --for=condition=Ready pod -l 'app.kubernetes.io/name=vault' -n appcircle --timeout=300s && \ echo "The databases are ready for migration steps." ``` From eb4fdc609cff7188bb4c66d2654916b27273ced3 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 6 Feb 2025 12:25:53 +0300 Subject: [PATCH 32/40] added mapping table --- .../installation/docker-k8s-migration.md | 250 ++++++++++-------- 1 file changed, 136 insertions(+), 114 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index c024d71d9..403838ad9 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -42,7 +42,7 @@ This migration process involves downtime. To minimize disruption, **plan accordi ::: :::info -In this documentation, we will migrate from a **standalone Appcircle server** to a **Kubernetes-based Appcircle server** using the **internal stateful applications** (PostgreSQL, MongoDB, MinIO, Vault) provided by the Appcircle Helm chart. +In this documentation, we will migrate from a **standalone Appcircle server** to a **Kubernetes-based Appcircle server** using the **internal stateful applications** (PostgreSQL, MongoDB, MinIO, Vault) provided by the Appcircle Helm chart. If you choose to use **external stateful services**, you will need to adapt certain migration commands to fit your **custom environment**. Specific commands requiring modifications for external deployments are highlighted in the relevant sections of this documentation. @@ -83,7 +83,7 @@ By default, Appcircle uses seven subdomains. These subdomains are: If the **standalone Appcircle server** is already using **HTTPS**, you **should provide an SSL certificate** for the Appcircle server Kubernetes deployment. :::tip -You can reuse the SSL certificates from your standalone Appcircle server for the Kubernetes deployment. These certificates can be found in your standalone server's `global.yaml` or `user-secret` file. This will ensure consistency and avoid the need to generate new certificates. +You can reuse the SSL certificates from your standalone Appcircle server for the Kubernetes deployment. These certificates can be found in your standalone server's `global.yaml` or `user-secret` file. This will ensure consistency and avoid the need to generate new certificates. ::: If the **standalone Appcircle server** uses **HTTP**, you can **skip configuring an SSL certificate**. @@ -359,8 +359,8 @@ Before proceeding with the migration, verify that the standalone Appcircle serve Before the migration, you should check the version of the Appcircle server and take the following actions: - **Check the latest standalone Appcircle server version:** - - Please check the standalone Appcircle server [version history](https://docs.appcircle.io/self-hosted-appcircle/install-server/linux-package/update#version-history) to learn the latest version. + + Please check the standalone Appcircle server [version history](https://docs.appcircle.io/self-hosted-appcircle/install-server/linux-package/update#version-history) to learn the latest version. - **Log in to the standalone Appcircle server:** @@ -377,19 +377,20 @@ Before the migration, you should check the version of the Appcircle server and t ```bash ./ac-self-hosted.sh -n spacetech version ``` - - If the version of the standalone Appcircle server is the latest: - - You can proceed with using the latest Appcircle Helm chart. - - - If the Appcircle server version is greater than or equal to `3.23.2`: - - You may opt to install a Helm chart version that corresponds to your specific standalone Appcircle server version. - - Please check the [version history of the Helm chart](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/upgrades#version-history) and use the latest Helm chart version for that version. - - If the Appcircle server version is earlier than `3.23.2`: - - [Update the standalone Appcircle server](/self-hosted-appcircle/install-server/linux-package/update.md) to at least version `3.23.2` prior to initiating the migration. + - If the version of the standalone Appcircle server is the latest: + - You can proceed with using the latest Appcircle Helm chart. + - If the Appcircle server version is greater than or equal to `3.23.2`: + + - You may opt to install a Helm chart version that corresponds to your specific standalone Appcircle server version. + - Please check the [version history of the Helm chart](https://docs.appcircle.io/self-hosted-appcircle/install-server/helm-chart/upgrades#version-history) and use the latest Helm chart version for that version. + + - If the Appcircle server version is earlier than `3.23.2`: + - [Update the standalone Appcircle server](/self-hosted-appcircle/install-server/linux-package/update.md) to at least version `3.23.2` prior to initiating the migration. #### 6. Find the Organization Name -To migrate the Appcircle server data, you should find the name of the current organization. +To migrate the Appcircle server data, you should find the name of the current organization. To find the organization name: @@ -630,7 +631,7 @@ For detailed instructions, refer to the [storage configuration](/self-hosted-app The SSL configuration of the Appcircle server Helm chart should match the SSL configuration used by the standalone Appcircle server. - If the standalone server is using HTTPS, configure the Helm chart for HTTPS. - - For more information about the SSL configuration, please check the [SSL configuration](/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration) page. + - For more information about the SSL configuration, please check the [SSL configuration](/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration) page. - If the server is running on HTTP, adjust the Helm chart configuration for HTTP. #### **Keycloak Updates** @@ -652,7 +653,7 @@ cd appcircle-k8s-migration grep 'initialOrganizationId' generated-secret.yaml ``` -4. Also get the organization name you have checked from the [step above](#6-find-the-organization-name). +4. Also get the organization name you have checked from the [step above](#6-find-the-organization-name). Here’s an example configuration for `values.yaml`: @@ -711,7 +712,6 @@ The `redis` subdomain used on the standalone Appcircle server has been updated t Review the `global.yaml` file from your standalone Appcircle server for any custom configurations. Compare these settings with the Appcircle Helm chart documentation and apply them in your `values.yaml` if supported. This ensures consistency and avoids potential issues during migration. - ### 4. Create Kubernetes Secrets This section details the creation of Kubernetes secrets required for Appcircle to function correctly. These secrets store sensitive information such as passwords and certificates, securely injecting them into your Appcircle deployment. @@ -722,62 +722,62 @@ Ensure you have [gathered all necessary data](#2-backup-appcircle-configuration- Some secret data, such as database passwords and Keycloak client secrets, used in the Kubernetes secrets creation below should match the data extracted from the backups of the standalone server. Ensure consistency between the backed-up values and the values used in the Kubernetes secrets to prevent connectivity and authentication issues. ::: -- **Create a namespace:** +- **Create a namespace:** - For the Appcircle server deployment. In this documentation, we will use `appcircle` as the example namespace. + For the Appcircle server deployment. In this documentation, we will use `appcircle` as the example namespace. - ```bash - kubectl create namespace appcircle - ``` + ```bash + kubectl create namespace appcircle + ``` --- - **Create Container Registry Secret:** - By default, Appcircle uses its own image registry, which requires authentication with the `cred.json` file provided by Appcircle. + By default, Appcircle uses its own image registry, which requires authentication with the `cred.json` file provided by Appcircle. - If you are using your own container image registry to access Appcircle container images, you can either skip authentication if your registry doesn't require it or create a secret for your custom registry. + If you are using your own container image registry to access Appcircle container images, you can either skip authentication if your registry doesn't require it or create a secret for your custom registry. - Follow the steps below to create the registry secret in the `appcircle` namespace for pods to successfully pull images: + Follow the steps below to create the registry secret in the `appcircle` namespace for pods to successfully pull images: - :::info - If you are using your own container registry, follow the `Custom Registry` section below. + :::info + If you are using your own container registry, follow the `Custom Registry` section below. - If your registry doesn't require authentication, you can skip this section. - ::: + If your registry doesn't require authentication, you can skip this section. + ::: - - Save the `cred.json` file. + - Save the `cred.json` file. - - Create the container registry secret: + - Create the container registry secret: - ```bash - kubectl create secret docker-registry containerregistry \ - -n appcircle \ - --docker-server='europe-west1-docker.pkg.dev' \ - --docker-username='_json_key' \ - --docker-password="$(cat cred.json)" - ``` + ```bash + kubectl create secret docker-registry containerregistry \ + -n appcircle \ + --docker-server='europe-west1-docker.pkg.dev' \ + --docker-username='_json_key' \ + --docker-password="$(cat cred.json)" + ``` - :::tip - If the `HISTCONTROL` environment variable is set to `ignoreboth`, commands with a leading space character will not be stored in the shell history. This allows you to create secrets safely without storing sensitive information in the shell history. - ::: + :::tip + If the `HISTCONTROL` environment variable is set to `ignoreboth`, commands with a leading space character will not be stored in the shell history. This allows you to create secrets safely without storing sensitive information in the shell history. + ::: - - Update the `server`, `username`, and `password` fields for your own custom registry and create the container registry secret: + - Update the `server`, `username`, and `password` fields for your own custom registry and create the container registry secret: - ```bash - kubectl create secret docker-registry containerregistry \ - -n appcircle \ - --docker-server='registry.spacetech.com' \ - --docker-username='yourRegistryUsername' \ - --docker-password='superSecretRegistryPassword' - ``` + ```bash + kubectl create secret docker-registry containerregistry \ + -n appcircle \ + --docker-server='registry.spacetech.com' \ + --docker-username='yourRegistryUsername' \ + --docker-password='superSecretRegistryPassword' + ``` @@ -786,75 +786,92 @@ Some secret data, such as database passwords and Keycloak client secrets, used i - **Keycloak Clients Secret:** - Create a secret with the name `${releaseName}-auth-keycloak-clients-secret` containing the relevant secret keys. + Create a secret with the name `${releaseName}-auth-keycloak-clients-secret` containing the relevant secret keys. - :::info - In the example, **`appcircle-server`** is used as the **release name**. Make sure to replace it with your actual release name if it's different. - ::: + :::info + In the example, **`appcircle-server`** is used as the **release name**. Make sure to replace it with your actual release name if it's different. + ::: - :::caution - The client secret values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.clients` key in the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. - ::: + :::caution + The client secret values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. + You can check the `.keycloak.clients` key in the `generated-secret.yaml` file. - ```bash - kubectl create secret generic appcircle-server-auth-keycloak-clients-secret \ - -n appcircle \ - --from-literal=appcircleWeb='dc589939-******-87b57fc1a1c7' \ - --from-literal=buildServer='307f6946-******-9d7743294f6a' \ - --from-literal=distributionAdminService='a286d519-******-227dec040f53' \ - --from-literal=distributionTesterWeb='7cc0c02a-******-5e7139d63f3c' \ - --from-literal=licenseServer='e198b11a-******-1ac96174d6f7' \ - --from-literal=publishServer='7965798e-******-0b4e8af8afed' \ - --from-literal=reportingServer='88e3abfd-******-afd2e2a1263f' \ - --from-literal=storeAdminService='f263f48f-******-588c9f55b4e3' \ - --from-literal=storeServer='08839b8d-******-aff4ecb63703' \ - --from-literal=storeWeb='9f6a406e-******-a88c17d7c2f6' \ - --from-literal=distributionServer='7cc0c02a-******-5e7139d63f3c' - ``` + Using incorrect values will prevent Appcircle from functioning correctly. + ::: + + | Source Key from `generated-secret.yaml` | Target Key | + | ----------------------------------------------- | -------------------------- | + | `keycloak.clients.appcircleWebSecret` | `appcircleWeb` | + | `keycloak.clients.buildServerSecret` | `buildServer` | + | `keycloak.clients.distributeAdminServiceSecret` | `distributionAdminService` | + | `keycloak.clients.testerWebSecret` | `distributionTesterWeb` | + | `keycloak.clients.licenseServerSecret` | `licenseServer` | + | `keycloak.clients.publishServerSecret` | `publishServer` | + | `keycloak.clients.reportingServerSecret` | `reportingServer` | + | `keycloak.clients.storeAdminServiceSecret` | `storeAdminService` | + | `keycloak.clients.storeServerSecret` | `storeServer` | + | `keycloak.clients.storeWebSecret` | `storeWeb` | + | `keycloak.clients.distributionServerSecret` | `distributionServer` | + + ```bash + kubectl create secret generic appcircle-server-auth-keycloak-clients-secret \ + -n appcircle \ + --from-literal=appcircleWeb='dc589939-******-87b57fc1a1c7' \ + --from-literal=buildServer='307f6946-******-9d7743294f6a' \ + --from-literal=distributionAdminService='a286d519-******-227dec040f53' \ + --from-literal=distributionTesterWeb='7cc0c02a-******-5e7139d63f3c' \ + --from-literal=licenseServer='e198b11a-******-1ac96174d6f7' \ + --from-literal=publishServer='7965798e-******-0b4e8af8afed' \ + --from-literal=reportingServer='88e3abfd-******-afd2e2a1263f' \ + --from-literal=storeAdminService='f263f48f-******-588c9f55b4e3' \ + --from-literal=storeServer='08839b8d-******-aff4ecb63703' \ + --from-literal=storeWeb='9f6a406e-******-a88c17d7c2f6' \ + --from-literal=distributionServer='7cc0c02a-******-5e7139d63f3c' + ``` --- - **Keycloak Passwords Secret:** - Create a secret with the name `${releaseName}-auth-keycloak-passwords` containing the relevant secret keys. + Create a secret with the name `${releaseName}-auth-keycloak-passwords` containing the relevant secret keys. - :::info - In the example, **`appcircle-server`** is used as the **release name**. Make sure to replace it with your actual release name if it's different. - ::: + :::info + In the example, **`appcircle-server`** is used as the **release name**. Make sure to replace it with your actual release name if it's different. + ::: - :::caution - The Keycloak password values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.password` key for the `adminPassword` and `.keycloak.initialPassword` for the `initialPassword` in the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. - ::: + :::caution + The Keycloak password values used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.keycloak.password` key for the `adminPassword` and `.keycloak.initialPassword` for the `initialPassword` in the `generated-secret.yaml` file. Using incorrect values will prevent Appcircle from functioning correctly. + ::: - ```bash - kubectl create secret generic appcircle-server-auth-keycloak-passwords \ - -n appcircle \ - --from-literal=initialPassword= \ - --from-literal=adminPassword= - ``` + ```bash + kubectl create secret generic appcircle-server-auth-keycloak-passwords \ + -n appcircle \ + --from-literal=initialPassword= \ + --from-literal=adminPassword= + ``` --- - **MinIO Connection Secret:** - Create a secret with the name `${releaseName}-minio-connection` containing the relevant secret keys. + Create a secret with the name `${releaseName}-minio-connection` containing the relevant secret keys. - :::info - In the example, **`appcircle-server`** is used as the **release name**. Make sure to replace it with your actual release name if it's different. - ::: + :::info + In the example, **`appcircle-server`** is used as the **release name**. Make sure to replace it with your actual release name if it's different. + ::: - :::caution - The MinIO keys used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.minio.secretKey` key in the `generated-secret.yaml` file for the `accessKey` and `root-password` in the example command below. Using incorrect values will prevent Appcircle from functioning correctly. - ::: + :::caution + The MinIO keys used below should match the data extracted from the `generated-secret.yaml` backup of your standalone Appcircle server. You can check the `.minio.secretKey` key in the `generated-secret.yaml` file for the `accessKey` and `root-password` in the example command below. Using incorrect values will prevent Appcircle from functioning correctly. + ::: - ```bash - kubectl create secret generic appcircle-server-minio-connection \ - -n appcircle \ - --from-literal=accessKey=admin \ - --from-literal=secretKey= \ - --from-literal=root-user=admin \ - --from-literal=root-password= - ``` + ```bash + kubectl create secret generic appcircle-server-minio-connection \ + -n appcircle \ + --from-literal=accessKey=admin \ + --from-literal=secretKey= \ + --from-literal=root-user=admin \ + --from-literal=root-password= + ``` ### 5. Add the Appcircle Helm Repository @@ -886,6 +903,7 @@ helm install appcircle-server appcircle/appcircle \ -f values.yaml --version 0.1.1 ``` + ::: :::warning @@ -939,6 +957,7 @@ echo "The databases are ready for migration steps." 1. **Log in to the bastion host.** 2. **Change directory to the temporary directory that was created for storing the standalone Appcircle server files:** + ```bash cd appcircle-k8s-migration ``` @@ -973,6 +992,7 @@ If you have used an **external PostgreSQL service** instead of the one provided ```bash sudo apt install postgresql-client-14 ``` + ::: 7. **Start Port Forwarding:** @@ -1063,12 +1083,13 @@ If you have used an **external PostgreSQL service** instead of the one provided cat projects/spacetech/export/publish/default.env | grep "CUSTOMCONNSTR_PUBLISH_DB_CONNECTION_STRING" ``` -9. **Dump the MongoDB:** - ```bash - docker exec -it spacetech-mongo_1-1 mongodump --uri="mongodb://backup:backup@mongo_1:36300,mongo_2:36301,mongo_3:36302/?replicaSet=rs&authSource=admin" --gzip --archive=/mongo-backup.gz - ``` +10. **Dump the MongoDB:** -9. **Copy the dumped DB file from out of the container to the host machine:** + ```bash + docker exec -it spacetech-mongo_1-1 mongodump --uri="mongodb://backup:backup@mongo_1:36300,mongo_2:36301,mongo_3:36302/?replicaSet=rs&authSource=admin" --gzip --archive=/mongo-backup.gz + ``` + +11. **Copy the dumped DB file from out of the container to the host machine:** ```bash docker cp spacetech-mongo_1-1:/mongo-backup.gz . ``` @@ -1160,7 +1181,8 @@ If you have used an **external MinIO service** instead of the one provided with kubectl get services -n appcircle | grep minio ``` -6. **Start port forwarding:** +5. **Start port forwarding:** + ```bash kubectl port-forward service/appcircle-server-minio 9000:9000 -n appcircle ``` @@ -1329,31 +1351,31 @@ If you have used an **external Vault service** instead of the one provided with kubectl get statefulsets -n appcircle | grep vault ``` -4. **Edit the vault `statefulset` for safe operations:** +5. **Edit the vault `statefulset` for safe operations:** ```bash kubectl patch statefulset -n appcircle appcircle-server-vault -p '{"spec": {"template": {"spec":{"containers":[{"name":"vault","command": ["sh", "-c", "tail -f /dev/null" ], "args": null, "readinessProbe": null, "lifecycle": null }]}}}}' ``` -5. **Delete the pod for it to be re-created:** +6. **Delete the pod for it to be re-created:** ```bash kubectl delete pod appcircle-server-vault-0 -n appcircle ``` -6. **Copy the vault data to the target pod:** +7. **Copy the vault data to the target pod:** ```bash kubectl cp "./vaultd.tar.gz" "appcircle-server-vault-0:/vault/data/vaultd.tar.gz" -n appcircle ``` -7. **Open shell in the vault container:** +8. **Open shell in the vault container:** ```bash kubectl exec -it appcircle-server-vault-0 -- bash ``` -8. **Run the following commands in the shell:** +9. **Run the following commands in the shell:** ```bash cd /vault/data @@ -1361,13 +1383,13 @@ If you have used an **external Vault service** instead of the one provided with /usr/local/bin/docker-entrypoint.sh vault server -config=/vault/config/extraconfig-from-values.hcl ``` -9. **Don't close the upper terminal until the process finishes:** +10. **Don't close the upper terminal until the process finishes:** -10. **Open a new terminal in the vault container:** +11. **Open a new terminal in the vault container:** - ```bash - kubectl exec -it appcircle-server-vault-0 -- bash - ``` +```bash +kubectl exec -it appcircle-server-vault-0 -- bash +``` 11. **Unseal the vault with the saved keys from the steps above:** From 65a39a4c58c2127f4f00f2f1a5d72b94b6d98d81 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 6 Feb 2025 12:28:37 +0300 Subject: [PATCH 33/40] add mkdir for dumped files --- .../helm-chart/installation/docker-k8s-migration.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 403838ad9..2716284d9 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -947,7 +947,13 @@ echo "The databases are ready for migration steps." docker exec pg_dump -U keycloak -h localhost -p 5432 -F c -b -v -f pgdump.backup keycloak ``` -3. **Copy Dump:** Copy the file from container to Appcircle server host. +3. **Create a directory to save dumped files.** + + ```bash + mkdir ~/appcircle-k8s-migration/ + ``` + +4. **Copy Dump:** Copy the file from container to Appcircle server host. ```bash docker cp :/pgdump.backup ~/appcircle-k8s-migration/ ``` From e8d7080a2e703b40f5b0c79bdf9830db927fdf0b Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 6 Feb 2025 12:30:55 +0300 Subject: [PATCH 34/40] add info for backup user --- .../helm-chart/installation/docker-k8s-migration.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 2716284d9..0043552b0 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -1067,6 +1067,12 @@ If you have used an **external PostgreSQL service** instead of the one provided 6. **Create a user to dump the DB:** + :::info + The backup user `backup` with password `backup` created for dumping the MongoDB database on the standalone Appcircle server will be migrated to the target Kubernetes environment. + + **It is strongly recommended to either delete this user after the migration is complete or change its password to a strong, unique one.** Leaving this user with the default password poses a significant security risk. + ::: + ```mongosh db.createUser({user: "backup",pwd: "backup",roles: [{ role: "root", db: "admin"}]}) ``` From 6b2778832c531d8d0d10c4707895b3b035dc4fcb Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 6 Feb 2025 12:39:51 +0300 Subject: [PATCH 35/40] add mongodb resource preset --- .../installation/docker-k8s-migration.md | 52 ++++++++++++++----- 1 file changed, 38 insertions(+), 14 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 0043552b0..331dbfa17 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -1103,7 +1103,7 @@ If you have used an **external PostgreSQL service** instead of the one provided 11. **Copy the dumped DB file from out of the container to the host machine:** ```bash - docker cp spacetech-mongo_1-1:/mongo-backup.gz . + docker cp spacetech-mongo_1-1:/mongo-backup.gz ~/appcircle-k8s-migration/ ``` #### Bastion Host @@ -1222,8 +1222,8 @@ If you have used an **external MinIO service** instead of the one provided with ```plaintext n # Create a new remote name> ac-standalone # Provide a descriptive name for the remote - Storage> 4 # Select "Amazon S3 Compliant Storage Provider" (4) - provider> 7 # Select "Minio Object Storage" (7) + Storage> 4 (might change) # Select "Amazon S3 Compliant Storage Provider" (4) + provider> 7 (might change) # Select "MinIO Object Storage" (7) env_auth> "false" # Set environment authentication to "false" access_key_id> # Enter the standalone Appcircle server's access key secret_access_key> # Enter the standalone Appcircle server's secret access key @@ -1251,13 +1251,13 @@ If you have used an **external MinIO service** instead of the one provided with ```plaintext n # Create a new remote name> ac-k8s # Provide a descriptive name for the remote - Storage> 4 # Select "Amazon S3 Compliant Storage Provider" (4) - provider> 7 # Select "Minio Object Storage" (7) + Storage> 4 (might change) # Select "Amazon S3 Compliant Storage Provider" (4) + provider> 7 (might change) # Select "MinIO Object Storage" (7) env_auth> "false" # Set environment authentication to "false" - access_key_id> # Enter the standalone Appcircle server's access key - secret_access_key> # Enter the standalone Appcircle server's secret access key + access_key_id> # Enter the K8s Appcircle server MinIO access key + secret_access_key> # Enter the K8s Appcircle server MinIO secret access key region> # Leave this empty - endpoint> # Provide the standalone Appcircle server's IP and MinIO port. Example: http://127.0.0.1:9000 + endpoint> # Provide the K8s Appcircle server MinIO IP and MinIO port. Example: http://127.0.0.1:9000 location_constraint: # Leave this empty acl: # Leave this empty server_side_encryption: # Leave this empty @@ -1277,10 +1277,10 @@ If you have used an **external MinIO service** instead of the one provided with 1. **Log in to the standalone Appcircle server:** -2. **Change directory to appcircle-server:** +2. **Change directory to the migration directory:** ```bash - cd appcircle-server + cd appcircle-k8s-migration ``` 3. **Create a file named `migrate.hcl`:** @@ -1326,7 +1326,7 @@ If you have used an **external MinIO service** instead of the one provided with 8. **Copy the tarball to the host machine:** ```bash - docker cp spacetech-vault-1:/vault/vaultd.tar.gz . + docker cp spacetech-vault-1:/vault/vaultd.tar.gz ~/appcircle-k8s-migration/ ``` 9. **Get the full path of the copied tarball:** @@ -1336,6 +1336,12 @@ If you have used an **external MinIO service** instead of the one provided with +9. **Change directory to the Appcircle server:** + + ```bash + cd appcircle-server + ``` + 10. **Get the unseal and root keys and save, you will use for unsealing the vault:** ```bash grep -A 7 "vault" projects/spacetech/generated-secret.yaml @@ -1384,7 +1390,7 @@ If you have used an **external Vault service** instead of the one provided with 8. **Open shell in the vault container:** ```bash - kubectl exec -it appcircle-server-vault-0 -- bash + kubectl exec -it appcircle-server-vault-0 -n appcircle -- bash ``` 9. **Run the following commands in the shell:** @@ -1434,8 +1440,26 @@ After the migration is completed, you need to enable the Keycloak module. - **Remove Keycloak Replica Override:** Delete the `replicas: 0` setting under `auth-keycloak`. -- **Remove MongoDB Resource Preset:** - Delete the `resourcesPreset` setting under `mongodb` if you don't need it. +- **Adjust MongoDB Resource Preset:** + + - **MongoDB Resource Preset:** You can adjust the resource allocation for your MongoDB deployment based on your needs. Here are some example `resourcesPreset` values you can use in your `values.yaml` file: + + | Size | CPU Requests | CPU Limits | Memory Requests | Memory Limits | Ephemeral Storage Requests | Ephemeral Storage Limits | + |-----------|--------------|------------|-----------------|---------------|---------------------------|--------------------------| + | nano | 100m | 150m | 128Mi | 192Mi | 50Mi | 2Gi | + | micro | 250m | 375m | 256Mi | 384Mi | 50Mi | 2Gi | + | small | 500m | 750m | 512Mi | 768Mi | 50Mi | 2Gi | + | medium | 500m | 750m | 1024Mi | 1536Mi | 50Mi | 2Gi | + | large | 1.0 | 1.5 | 2048Mi | 3072Mi | 50Mi | 2Gi | + | xlarge | 1.0 | 3.0 | 3072Mi | 6144Mi | 50Mi | 2Gi | + | 2xlarge | 2.0 | 6.0 | 6144Mi | 12288Mi | 50Mi | 2Gi | + + For example, to set a "medium" resource preset, add the following to your `values.yaml` file under the `mongodb` section: + + ```yaml + mongodb: + resourcesPreset: "medium" + ``` ### 2. Upgrade the Helm Release From 8633688604bc064c88a8b72f1eb6c5426ae55727 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 6 Feb 2025 12:41:02 +0300 Subject: [PATCH 36/40] add delete vault --- .../helm-chart/installation/docker-k8s-migration.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 331dbfa17..20928bb10 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -1480,6 +1480,12 @@ Restart all the Appcircle server deployments to make sure every service is resta kubectl rollout restart deployment -n appcircle ``` +Delete the Vault pod to trigger its recreation with the updated configuration. + +```bash +kubectl delete pod appcircle-server-vault-0 -n appcircle +``` + ### 4. Update the DNS Records List the Ingresses with `kubectl` to check the IP address of the Appcircle services domains. From 15776ecb0383c5db46e99835d4b1498950a4b604 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 6 Feb 2025 12:45:29 +0300 Subject: [PATCH 37/40] add caution not to change config files --- .../helm-chart/installation/docker-k8s-migration.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 20928bb10..6ec023a7b 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -49,6 +49,14 @@ If you choose to use **external stateful services**, you will need to adapt cert In the case of using **external stateful services**, the **bastion host requirements** should be adjusted to meet your **specific setup**. For example, the **storage** and **access requirements** for the external databases and services will need to be accounted for during the migration. Please ensure that your **bastion host** is configured with appropriate resources and network access to support these **external services**. ::: +:::warning Don't make any changes on the configuration files while migration +**Do not change any configurations** on your standalone Appcircle server or on the K8s configuration file during the migration process. + +Any changes made before the successful migration to Kubernetes are unsupported and may lead to data loss or unexpected behavior. + +If you need to modify configurations such as SMTP settings, wait until the migration is complete and then use the relevant configuration documentation to make the changes on the Kubernetes-based Appcircle server. +::: + ## Prerequisites To complete this guide, you must have the following: From 7ebada96ebbc99a887a18958efe1a540af652e34 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Thu, 6 Feb 2025 13:09:28 +0300 Subject: [PATCH 38/40] add enterprise app store custom domain section --- .../configuration/enterprise-store-configuration.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/enterprise-store-configuration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/enterprise-store-configuration.md index 3a0588f3a..2b6ba2fb0 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/enterprise-store-configuration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/enterprise-store-configuration.md @@ -17,6 +17,10 @@ You can change how your store looks using the **[Customize](/enterprise-app-stor For self-hosted specific settings, you should follow the documentation below. +## Custom Domain + +To configure a custom domain for your Enterprise App Store, follow the instructions on the [Enterprise App Store settings page](/docs/enterprise-app-store/portal-settings.md#custom-domain). + ## Tab Title Localization You can change the Enterprise App Store tab title according to the language selected on the self-hosted Appcircle server. From 81232c356250341f5dc8bfcb68224ee1b036a166 Mon Sep 17 00:00:00 2001 From: Burak Berk Date: Mon, 10 Feb 2025 14:55:33 +0300 Subject: [PATCH 39/40] fix grammar mistakes --- .../helm-chart/installation/docker-k8s-migration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 6ec023a7b..7af5da12e 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -49,7 +49,7 @@ If you choose to use **external stateful services**, you will need to adapt cert In the case of using **external stateful services**, the **bastion host requirements** should be adjusted to meet your **specific setup**. For example, the **storage** and **access requirements** for the external databases and services will need to be accounted for during the migration. Please ensure that your **bastion host** is configured with appropriate resources and network access to support these **external services**. ::: -:::warning Don't make any changes on the configuration files while migration +:::warning Don't make any changes on the configuration files while migrating **Do not change any configurations** on your standalone Appcircle server or on the K8s configuration file during the migration process. Any changes made before the successful migration to Kubernetes are unsupported and may lead to data loss or unexpected behavior. @@ -1076,9 +1076,9 @@ If you have used an **external PostgreSQL service** instead of the one provided 6. **Create a user to dump the DB:** :::info - The backup user `backup` with password `backup` created for dumping the MongoDB database on the standalone Appcircle server will be migrated to the target Kubernetes environment. + The backup user `backup` with a password `backup` created for dumping the MongoDB database on the standalone Appcircle server will be migrated to the target Kubernetes environment. - **It is strongly recommended to either delete this user after the migration is complete or change its password to a strong, unique one.** Leaving this user with the default password poses a significant security risk. + **It is strongly recommended to either delete this user after the migration is complete or change its password to a strong, unique one.** Leaving this user with the default password poses a significant security risk. ::: ```mongosh From 4242dda77fff4783c1877bdbdab8852535f419ae Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Fri, 7 Mar 2025 15:57:27 +0300 Subject: [PATCH 40/40] add required annotation and label --- .../installation/docker-k8s-migration.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md index 7af5da12e..7735b3025 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/installation/docker-k8s-migration.md @@ -838,6 +838,21 @@ Some secret data, such as database passwords and Keycloak client secrets, used i --from-literal=distributionServer='7cc0c02a-******-5e7139d63f3c' ``` + Add required labels and annotations. + + :::info + If you have changed the default namespace (`appcircle`) or the default release name (`appcircle-server`), + ::: + + ```bash + kubectl label secret -n appcircle appcircle-server-auth-keycloak-clients-secret \ + -n appcircle app.kubernetes.io/managed-by=Helm && \ + kubectl annotate secret -n appcircle appcircle-server-auth-keycloak-clients-secret \ + -n appcircle \ + meta.helm.sh/release-name=appcircle-server \ + meta.helm.sh/release-namespace=appcircle + ``` + --- - **Keycloak Passwords Secret:**