Importing projects in the CES setup
This article describes how Terraform projects can be imported during the CES setup.
Prerequisites
The following prerequisites must be met for a successful project import.
- The dogus specified in the projects to be imported must be installed.
- All dogus that are installed must be in
healthy
status after installation. -
The terraform providers used in the projects to be imported must be either
- be present in the terraform registry (so that they can be downloaded from there)
- or be installed manually (see below for details)
- ces-commons must be available in a version >= 0.5.0.
Configuration in setup.json
For the import of projects, a projects
block in setup.json must be configured in the following way.
"projects":{
"external_admin_username": "<Username>",
"external_admin_password": "<Password>",
"import":[
{
"username":"<Username>",
"password":"<Password>",
"type":"Git",
"location":"https://github.com/cloudogu/demo-content-petclinic",
"reference":{
"name":"0.0.1",
"type":"Tag"
}
}
],
"completed":true
},
Properties
externaladminusername
- Data type:
String
- Optional: Required when using an external LDAP.
- Content: The username of the CES admin user.
externaladminpassword
- Data type:
String
- Optional: Required when using an external LDAP.
- Content: The password of the CES admin user.
import
- Data type: Project Array
- Contents: List of all projects that are to be imported.
Data type Project
username
- Data type: string
- Content: The username for authentication with the service (e.g. GitHub) from which the project to be imported is retrieved.
- If the
type
isArchive
and the archive can be downloaded without authentication, no username needs to be specified.
password
- Data type: string
- Content: The password for authentication with the service (e.g. GitHub) from which the project to be imported is retrieved.
- If the
type
isArchive
and the archive can be downloaded without authentication, no password needs to be specified. - Note: If the project is to be checked out from a GitHub repository and 2-factor authentication is enabled in GitHub, the normal password will not work. A console key must be generated in GitHub and used here instead of the password. For details see: https://docs.github.com/en/github/authenticating-to-github/accessing-github-using-two-factor-authentication
type
- Data type: string
- Content: The type of the project
-
Possible values:
- Archive
- for a ZIP archive located on any webserver
- Git
- for a Git repository
- the Git repository specified in
location
is cloned
location
- Data type: string
- Content: The location where the project is stored, e.g. a URL to a Git repository.
-
Depending on the
type
of the project.- Git:
- Specification of a Git repository.
- Example:
https://github.com/cloudogu/demo-content-petclinic
- Archives:
- Specification of a ZIP archive.
- The ZIP archive can be located on any web server.
- Example:
https://stagex.cloudogu.com/nexus/repository/Cloudogu-Docs/terraform-projects/demo-content-petclinic.zip
reference
- Data type: reference
- Content: A reference to a specific branch or a specific tag.
- Only evaluated if the
type
of the project isGit
- Optional
- If no reference is specified, the default branch of the repository is used.
Data type Reference
name
- Data type: string
- Content: A reference to a branch or tag.
- Example: feature/123_myBranch
type
- Data type: string
- Content: The type of the reference
- Possible values: Tag, Branch
Import via the user interface
The project import via the user interface is currently not yet implemented and can only be done via setup.json.
Procedure of the project import
- The import of projects is the last step of the setup and takes place after the installation and the start of the Dogus.
- In order for projects to be imported successfully, each installed dogu waits until the dogu has reached the health status. The timeout for waiting is 20 minutes per dogu.
- The projects are imported one after the other.
-
The first step is to check out a project.
- For Git projects, this is done via
git clone
. - For ZIP archives, the ZIP archive is downloaded and unpacked.
- For Git projects, this is done via
- The checked out project is imported with
terraform init
andterraform apply
. - If an error occurs, the setup is aborted at the point where the error occurred.
- Into which dogus something should be imported and which terraform providers should be used is defined in the terraform project. The CES setup does not check whether the dogus and terraform providers are available.
Manual installation of a terraform provider
- To manually install a local terraform provider, it must be placed in the user's home directory under
.terraform.d/plugins
. - The terraform provider must be placed according to the following substructure:
<namespace>/tf/<name>/<version>/<distribution>
. - Example: The terraform-provider-scm must be copied in the local CES to the following directory:
/root/.terraform.d/plugins/cloudogu.com/tf/scm/1.0/linux_amd64
. - When building a terraform provider locally, the appropriate substructure is already created.
- For detailed instructions, see here