Upgrade Guides

GoodData.CN Container Edition

From version 1.2.0, it’s recommended to store metadata from your GoodData.CN Container Edition (CE) installation in a docker volume. Alternatively, you may store the metadata elsewhere. How you upgrade your environment depends on where you store your metadata:

• If you are using a docker volume to store metadata from your GoodData.CN Container Edition container, download a new version of the GoodData.CN Container Edition docker image and start it with your volume. All your metadata will be migrated.
• If you are not using a docker volume to store metadata from your GoodData.CN container, follow the version specific and general upgrade guides. You must back up your metadata if you want to migrate it to the newer version.

GoodData.CN Container Edition Version Specific Upgrade Guides

Upgrading to a new minor version is supported only from the previous minor version. To upgrade over several minor versions, follow the upgrade path for each minor version separately. You will find this information in the release notes for each version.

General Upgrade Guide

After any version specific upgrades are complete, you may complete the general upgrade steps for GoodData.CN Container Edition.

Preparation

Before starting the upgrade, these two steps are necessary:

1. Set the general connection parameters as environment variables.

   • If you used the demo environment from the GoodData.CN Container Edition image, use the following values:

       export ENDPOINT=http://localhost:3000
       export API_TOKEN=YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz
     

   • If you set up your own environment, use the values specific to your environment.

2. Set versioned API endpoints as environment variables.

   • Prior GoodData.CN version 2.0 the API was not versioned, with the version 2.0 the URI contains version identifier. Set both environment variables for the current and the target deployment appropriately to state of your deployment. The following example expects as a current deployment a non-versioned API of the release 1.7 and target deployment of the release 2.0.

      export CURRENT_VERSION=api
      export TARGET_VERSION=api/v1
     

   • Version identifiers
     • 1.x - no version identifier
     • 2.0 - v1

3. Install a JSON command-line processor (all examples here use the “jq”).

Back Up the Current Working Environment

If you want to start with a new environment after the upgrade, you can back up the metadata for an entire organization of GoodData.CN Container Edition. This is optional.

Back Up the Organization

Backing up the entire organization is the simplest way to preserve an entire setup of a GoodData.CN Container Edition deployment. The retrieved metadata contains all objects of an organization (users, userGroups, workspaces, data sources).

Execute the following command to save all metadata of an organization as /tmp/organization-layout.json:

curl -L -H "Authorization: Bearer $API_TOKEN" \
  -X GET "$ENDPOINT/$CURRENT_VERSION/layout/organization" \
  > /tmp/organization-layout.json

Upgrade Your GoodData.CN Container Edition Image

Follow these steps:

1. Stop your current GoodData.CN Container Edition (CE) image.
2. Download the latest GoodData.CN Container Edition image from hub.docker.com.
3. Start the new GoodData.CN Container Edition image as usual.

Restore Your Previous Working Environment

If you backed up any of the metadata from your previous GoodData.CN Container Edition environment, you can restore that data.

Restore the Organization

The layout created using the command in Back Up the Organization needs to be updated before it can be imported into the new image. The following needs to be checked:

Data Source credentials

The exported organization layout doesn’t contain credentials to data sources. While the layout can be imported without any credentials specified for the data sources, doing so will make the data sources unusable. To add proper credentials to all data sources in the exported /tmp/organization-layout.json, follow these steps:

1. Prepare a credentials template for the data sources:

   jq --raw-output '.dataSources[] |
   if has("username") then "\(.id):password:" else "\(.id):token:" end' \
   /tmp/organization-layout.json > /tmp/data-sources-credentials.txt \
   && echo "Prepared template for credentials: /tmp/data-sources-credentials.txt"
   

2. Edit the created file /tmp/data-sources-credentials.txt - add token or password right after the rightmost colon on the line with a relevant data source, avoid whitespace before or after the tokens/password. This file will be automatically read during the next step.

   Note

   If you are restoring data from the demo data source (demo-ds), the following are the default credentials:

   • "username": "demouser"
   • "password": "demopass"

3. Update /tmp/organization-layout.json with the credentials:

   export SOURCE_LAYOUT=/tmp/organization-layout.json
   while read line ; do
     IFS=':'; parts=($line); unset IFS
     dataSource=${parts[0]}
     type=${parts[1]}
     credential=${parts[2]}
     echo "Processing credentials of type ${type} for data source ${dataSource}"
   
     jq --arg dataSource $dataSource --arg type $type --arg credential $credential \
     'setpath(path(.dataSources[] | select(.id == $dataSource)); .dataSources[] | select(.id == $dataSource) | . + { ($type): $credential})'\
     $SOURCE_LAYOUT > ${SOURCE_LAYOUT}-updated
   
     mv ${SOURCE_LAYOUT}-updated $SOURCE_LAYOUT
   done < /tmp/data-sources-credentials.txt
   

Authentication Provider Configuration

Note that the procedure differs for GoodData.CN Container Edition users and GoodData.CN Production K8S Edition users.

For GoodData.CN Container Edition users:

1. Get default organization entity:

   curl -L -H "Authorization: Bearer $API_TOKEN" \
     -H "Content-Type: application/vnd.gooddata.api+json" \
     -H "Accept: application/vnd.gooddata.api+json" \
     -X GET "$ENDPOINT/$TARGET_VERSION/entities/admin/organizations/default" \
     > /tmp/taget-default-org.json
   

2. Extract oauthClientID:

   TARGET_CLIENT_ID=$(jq --raw-output '.data.attributes.oauthClientId' /tmp/taget-default-org.json)
   

3. Move the extracted oauthClientID to the organization layout which is to be imported to your new version of GoodData.CN Container Edition:

   SOURCE_LAYOUT=/tmp/organization-layout.json
   jq --arg targetClientId $TARGET_CLIENT_ID \
     '.organization.oauthClientId = $targetClientId' \
     $SOURCE_LAYOUT > ${SOURCE_LAYOUT}-client-id && \
     mv ${SOURCE_LAYOUT}-client-id $SOURCE_LAYOUT
   

For GoodData.CN Production K8S Edition users:

The client secret for an organization is not retrieved when you export the organization layout. The authentication provider secret for the organization must be specified in the document before you perform the restore.

1. Define an environment variable named CLIENT_SECRET with the OIDC token value. We recommend write a plain token into a file, ex. client-secret.txt and then export the environment variable with content of that file so the token value is not persisted with the history of a shell.

   export CLIENT_SECRET=$(cat client-secret.txt)
   

2. Update the layout document.

   jq --arg oauth $CLIENT_SECRET '.organization.oauthClientSecret = $oauth' \
   /tmp/organization-layout.json > /tmp/organization-layout-updated.json
   

Apply version specific upgrades

Follow the instructions from version upgrade guides.

Perform the Restore

Once the layout created using the command in Back Up the Organization was updated as described in previous steps import the updated-layout.json file into your GoodData.CN deployment:

curl --data @/tmp/organization-layout.json \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-type: application/json" \
  -X PUT $ENDPOINT/$TARGET_VERSION/layout/organization

GoodData.CN Production K8S Edition

Upgrading to a new minor version is supported only from the previous minor version. To upgrade over several minor versions, follow the upgrade path for each minor version separately. You will find this information in the release notes for each version.

After any version specific upgrades are complete, you may complete the general upgrade steps for GoodData.CN Production K8S Edition. Execute the following statement to upgrade your GoodData.CN Production K8S Edition environment:

helm upgrade --namespace gooddata-cn --version n.n.n \
    -f customized-values-gooddata-cn.yaml \
    gooddata-cn gooddata/gooddata-cn

As a reminder of what each value refers to:

helm upgrade --namespace <NAMESPACE> --version n.n.n \
    -f customized-values-gooddata-cn.yaml \
    <YOUR_RELEASE_NAME> <HELM_REPOSITORY>/gooddata-cn

where:

• n.n.n is the version number of your current environment. For example, 1.2.0.
• customized-values-gooddata-cn.yaml is the file you should have created during installation
• gooddata-cn is the name of our helm chart and must not be changed.