Migrate from Earlier Versions
If you used Space On-Premises 2022.1 Beta, it is possible to transfer all your data to a new 2023.1 installation.
What you should take into account:
Space On-Premises supports only forward updates – it's not possible to downgrade to previous versions.
The Beta license is valid only till January 31, 2023. After that date, you won't be able to use your Space On-Premises instance though migration will still be possible.
The Space On-Premises Beta version provides the feature set equivalent to the Organization plan of the release version. Nevertheless, it's possible to migrate Space On-Premises Beta to the Free plan which has fewer features available. If your Beta installation has entities provided by the Organization plan, these entities will be migrated, but it will not be possible to create new similar entities.
Migration from Beta to 2023.1 cannot be performed without downtime, as it requires a complete shutdown of the old version before running the new one. Make sure to plan the maintenance window and inform your users about the upcoming activities.
Before migration
Back up Space data. Here you can find the primary considerations of what you should back up.
Space On-Premises Beta could create excessive index data in Elasticsearch. Before starting the migration, delete the redundant indices.
Run
bash
on the Elasticsearch host. For the Docker Compose installation:docker-compose -p space-on-premises run -it elasticsearch bashList all Elasticsearch indices. For the Docker Compose installation:
curl elasticsearch:9200/_cat/indices/space-automation.tracing*If there are more than 10 indices that match the
space-automation.tracing*
pattern, delete them. For the Docker Compose installation:curl -XDELETE elasticsearch:9200/space-automation.tracing*
How to migrate
The data migration process differs for the Docker Compose and Kubernetes installations.
The instructions imply that your Space On-Premises Beta instance is installed to the space-on-premises-beta
directory. The new Space On-Premises instance will be installed to the space-on-premises
directory.
Create and open an installation directory for the new Space instance:
mkdir -p space-on-premises && cd space-on-premisesDownload the latest version of the
docker-compose.yml
file from https://assets.on-premises.service.jetbrains.space/. For example, if the latest version is 2023.1.0:export SPACE_RELEASE_NAME="2023.1.0" curl -O "https://assets.on-premises.service.jetbrains.space/${SPACE_RELEASE_NAME}/docker-compose.yml"Migration requires editing Space configuration files, meaning that the files must be copied from a Space container to the host machine. If you customized your existing Space instance before, this is already done. If not, open the
space-on-premises-beta
directory and run:docker-compose -p space-on-premises run --entrypoint=cp -v {absolute_path_to_config_folder_on_host}:/home/copy-config init-configs -a /home/init-config/config/. /home/copy-configHere
{absolute_path_to_config_folder_on_host}
is the path to the configuration files destination directory on the host machine.Open the
space-on-premises
directory and create configuration files for the new Space version:docker-compose -p space-on-premises run --entrypoint=sh init-configs /prepare_default_configs.shCopy parameter values from the Beta version configuration files to the files of the new Space version. Here is the list of files and parameters which values must be copied:
space.on-premises.conf
:circlet.masterSecret
circlet.oauth.accessToken.rsa.public
circlet.oauth.accessToken.rsa.private
circlet.oauth.message.encoding.key
circlet.oauth.twoFactor.encryptionKey
circlet.oauth.encryptionKey
circlet.oauth.messageSigning.rsa.public
circlet.oauth.messageSigning.rsa.private
circlet.vcs.secret
circlet.vcs.identity.email
circlet.vcs.identity.secretKey_base64
circlet.webhooks.key
circlet.packages.oauth.clientSecret
packages.on-premises.conf
:circlet.packages.oauth.clientSecret
vcs.on-premises.conf
:circlet.key
vcs.sshServerKeyRSABase64
Vcs.gpg.public_key.base64
Open the
docker-compose.yml
file in thespace-on-premises
directory.Find the line that defines Java options for the Space service:
JAVA_OPTS: "-Dconfig.file=/home/space/circlet-server-onprem/config/space.on-premises.conf"and add one more option to it:
JAVA_OPTS: "-Dconfig.file=/home/space/circlet-server-onprem/config/space.on-premises.conf -Dcirclet.organization.domain=jetbrains"Now, you should make your new Space version (the one in the
space-on-premises
directory) use the created configuration files. To do this, enable customization of the Space service as described here.Stop the Beta instance of Space by running the following command in the
space-on-premises-beta
directory:docker-compose -p space-on-premises downStart the new Space instance by running the following command in the
space-on-premises
directory:docker-compose -p space-on-premises up
In a Kubernetes installation, PostgreSQL, a MinIO/S3-compatible storage, Elasticsearch, and Redis are configured as external services. You can continue using them in your new Space On-Premises instance.
Get the names of the Space deployment objects:
kubectl -n ${KUBE_NAMESPACE} get deployments -l app.kubernetes.io/name=space --output=jsonpath={..metadata.name}Gracefully shutdown all pods related to the objects from step 1:
for deployment in $(kubectl -n ${KUBE_NAMESPACE} get deployments -l app.kubernetes.io/name=space --output=jsonpath={..metadata.name}); do kubectl -n ${KUBE_NAMESPACE} scale deploy ${deployment} --replicas=0 doneRemove all deployment objects related to the Beta version of Space On-Premises:
for deployment in $(kubectl -n ${KUBE_NAMESPACE} get deployments -l app.kubernetes.io/name=space --output=jsonpath={..metadata.name}); do kubectl -n ${KUBE_NAMESPACE} delete deploy ${deployment} doneIf you installed your Space On-Premises instance using helm install (see Kubernetes Installation), upgrade the Helm release:
helm -n ${KUBE_NAMESPACE} upgrade ${SPACE_RELEASE_NAME} ${HELM_REPO}/${CHART_NAME} -f values.yamlHere
values.yaml
is the values file of your current Space On-Premises instance.Alternatively, you can generate manifests for your current Space instance and apply them with
kubectl
:helm -n ${KUBE_NAMESPACE} template ${SPACE_RELEASE_NAME} ${HELM_REPO}/${CHART_NAME} -f values.yaml | kubectl -n ${KUBE_NAMESPACE} apply -f-