Setting up your Development Environment

How to setup your development environment.

Setting up development environment

If you do not have Go SDK, you should download and configure it. To check the version required by SPEKTRA Edge, see this file - top shows the required minimum version. As of the moment of this writing, it is 1.21, but it may change. Ensure Go SDK is installed.

You will need to access the following repositories, ensure you have access to:

With Go SDK installed, check the $GOPATH variable: echo $GOPATH. Ensure the following paths exist:

Export variables, as they are referenced by various scripts:

export GOTENPATH=$GOPATH/src/github.com/cloudwan/goten
export EDGELQROOT=$GOPATH/src/github.com/cloudwan/edgelq

You may export them permanently.

Goten/SPEKTRA Edge comes with its own dependencies and plugins, you should install them:

$GOTENPATH/scripts/install-proto-deps.sh
$GOTENPATH/scripts/install-plugins.sh
$EDGELQROOT/scripts/install-edgelq-plugins.sh

You need some repository for your code, like github.com/some-namespace/some-repo. If you do that, ensure the location of this repository is in $GOPATH/src/some-namespace/some-repo, OR it is sym-linked there.

Reserving service on the SPEKTRA Edge platform

Before you begin here, ensure that you have access to some Organization where you have permission to create service projects - typically it means some administrator. You need cuttle configured - at least you should go through the user guide and reach the IAM chapter.

All service resources on the SPEKTRA Edge platform belong to some IAM project. An IAM Project that is capable of “hosting” services is called a “Service Project”. You may create many services under a single service project, but you need to make the first one.

# If you dont plan to create devices/applications resources under your service project, you should skip them
# using core-edgelq-service-opt-outs. It DOES NOT MEAN that final tenant projects using your service will not use
# those services, or that your service wont be able to use devices/applications. It merely says that your project
# will not use them.
cuttle iam setup-service-project project --name 'projects/$SERVICE_PROJECT_ID' --title 'Service Project' \
  --parent-organization 'organizations/$MY_ORGANIZATION_ID' --multi-region-policy '{"enabledRegions":["$REGION_ID"],"defaultControlRegion":"$REGION_ID"}' \
  --core-edgelq-service-opt-outs 'services/devices.edgelq.com' --core-edgelq-service-opt-outs 'services/applications.edgelq.com'

To clarify: A service project is just a container for services, and is used for some simple cases like usage metrics storage or service accounts. Therefore, eventually, you will have two resources:

  • IAM Service project: projects/$SERVICE_PROJECT_ID - it will contain credentials of ServiceAccounts with access to your service or usage metrics.
  • Meta Service: services/$YOUR_SERVICE

The service project is a type of IAM project, but your service tenants will have their projects. Service on its own is a separate entity from a project it belongs to. Therefore, unless your project will need to have some devices/applications resources directly, it is recommended to opt out from those services using --core-edgelq-service-opt-outs arguments. Your service will still be able to import/use devices/applications, and tenants using your service too.

You need to decide on $SERVICE_PROJECT_ID and $REGION_ID, where your service will run. As of this moment, SPEKTRA Edge platform is single-regional, so you will only have one region at your disposal. But it should change in the future. It will be possible to expand your service project (and therefore services) to more regions later on.

You will need to replace the $MY_ORGANIZATION_ID variable with one you have access to.

Once you have service project created, you will need to reserve a service:

cuttle iam reserve-service-name project --name 'projects/$SERVICE_PROJECT_ID' --service 'services/$YOUR_SERVICE_NAME' \
  --admin-account 'projects/$SERVICE_PROJECT_ID/regions/$REGION_ID/serviceAccounts/svc-admin' \
  --admin-key '{"name":"projects/$SERVICE_PROJECT_ID/regions/$REGION_ID/serviceAccounts/svc-admin/serviceAccountKeys/key", "algorithm":"RSA_2048"}' \
  -o json

Now you will need to determine the value of $YOUR_SERVICE_NAME - our 3rd party services are watchdog.edgelq.com, and ztna.edgelq.com. Those look like domains, but the actual public domain you can decide/reserve later on.

Argument --admin-account determines the ServiceAccount resource that will be allowed to create a given Service, and it will be responsible for its future management. If it does not exist, it will be created. You should be able to see it with:

cuttle iam get service-account 'projects/$SERVICE_PROJECT_ID/regions/$REGION_ID/serviceAccounts/svc-admin' -o json

The argument --admin-key is more important as it will create a ServiceAccountKey resource under the specified admin account. However, if the key already exists, you will receive an AlreadyExists error. This may occur if you were already making reservations for different services. If both ServiceAccount and ServiceAccountKey already exist in a given service project, you should skip using the --admin-key argument altogether and simply use previously obtained credentials. The same ServiceAccount can be used for many services. However, if you wish, you can decide to create another --admin-account by providing a different name than what was used before.

If you provide –admin-key argument, you can do this in two ways:

  --admin-key '{"name":"projects/$SERVICE_PROJECT_ID/regions/$REGION_ID/serviceAccounts/svc-admin/serviceAccountKeys/key", "algorithm":"RSA_2048"}'

OR

  --admin-key '{"name":"projects/$SERVICE_PROJECT_ID/regions/$REGION_ID/serviceAccounts/svc-admin/serviceAccountKeys/key", "publicKeyData":"$DATA"}'

In the case of the first example, the response will contain private key data contents that you will need. In the second case, you can create a private/public pair yourself and supply public data ($DATA param). This version should be used if you prefer to keep a private key never known by SPEKTRA Edge services.

You should pay attention to the response returned from cuttle iam reserve-service-name project. More specifically, field nttAdminCredentials:

{
  "nttAdminCredentials": {
    "type": "<TYPE>",
    "client_email": "<CLIENT_EMAIL>",
    "private_key_id": "<KEY_ID>",
    "private_key": "<PRIVATE_KEY>"
  }
}

You should get this value and save in own ntt-credentials.json file (you can name file however you like though):

{
  "type": "<TYPE>",
  "client_email": "<CLIENT_EMAIL>",
  "private_key_id": "<KEY_ID>",
  "private_key": "<PRIVATE_KEY>"
}

Note that, if you created –admin-key with the public key (not algorithm), then <PRIVATE_KEY> will not be present in response. Instead, when saving the ntt-credentials.json file, you should populate this value yourself with the private key.

Credentials need to be kept and not lost. In case it happens, you can use the DeleteServiceAccountKey method. Note that ServiceAccount (admin) for services is just a regular ServiceAccount in iam.edgelq.com service - and you have full CRUD of its ServiceAccountKey instances.

When reserving a service for the first time, you may also decide what Role will be assigned to a ServiceAccount for your service. By default, ServiceAccount will be an admin in the Service namespace, but it will have a limited role assigned in the projects/$SERVICE_PROJECT_ID scope. By default, it is services/iam.edgelq.com/roles/default-admin-project-role. However, for more advanced users, you can pass a custom role, for example, full ownership:

cuttle iam reserve-service-name project --admin-account-project-role 'services/iam.edgelq.com/roles/scope-admin' <OTHER ARGS>

You may manage service projects & services on SPEKTRA Edge dashboard as well. To have same API via Cuttle, see:

cuttle iam list-my-service-projects projects --help  # To see service projects
cuttle iam list-service-reservations project --help  # To see existing service reservations under specific service project.
cuttle iam delete-service-reservation project --help # To delete service reservation
cuttle iam list-project-services project --help      # To see already created services under specific service project

# This command is more advanced, should be used when expanding service project
# to new regions. Will be more covered in next docs in detail, for now its just
# FYI.
cuttle iam add-regional-admin-account-for-services service-account --help

With service reserved, you should continue with the normal development.