Skip to content

Configuring ce‐provision

Jump to bottom
Greg Harvey edited this page Jan 15, 2025 · 20 revisions

You can configure ce-provision by providing a Git repository with Ansible settings, customised playbooks, default variables, extra plugins and so forth. By default ce-provision will take its initial config from our example repo which is also a good one to copy to get started.

While you can store your configuration anywhere, this is a quick start guide so we will assume you have followed our installation steps and you are going to use the GitLab instance installed on your controller to house your ce-provision-config. This is how you fork our example repository into your own config repository, so you can take control of your own ce-provision-config.

Create a GitLab Runner

Before our GitLab instance can build anything we need to create a Runner, which will run commands on our controller for us:

  1. Logged into your controller server via SSH or browser terminal, switch to the controller user: sudo su -l controller
  2. Fetch the GitLab root password from the temporary file where it was created: cat /tmp/passwordfile
  3. In a web browser go to your GitLab installation, for example https://gitlab.controller.acme.com, and login with these details:
    • root
    • the password from /tmp/passwordfile (any problems, you can find initial_root_password in the file at /etc/gitlab/gitlab.rb)
    • Creating a user - you might at this point want to create a user, click Admin at the bottom of the page, on the admin page click New user and create your new user with Access level set to Administrator - you can then logout as root and login as this user instead
  4. Click the Admin button in the bottom left, then on the right-hand menu CI/CD -> Runners
  5. Click the New instance runner button in the top right
  6. On this page tick the Run untagged jobs box, write 'Default shell runner' in the Runner description box and click Create runner
  7. Leave Operating systems set to Linux, go back to your SSH session and follow the instructions underneath, you will be asked to provide:
    • URL - this should be pre-filled, so just hit Enter
    • name - enter 'Default shell runner' again and press Enter
    • executor - type 'shell' and press Enter

You should now see this message:

Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
 
Configuration (with the authentication token) was saved in "/etc/gitlab-runner/config.toml"

Create a blank repository on your GitLab instance

  1. Go back to the front of GitLab in your web browser by clicking on the logo in the top left
  2. Click Create a group -> Create group
    • we recommend you name it Core and leave it private
  3. On the next page click New project -> Create a blank project
    • we recommend you name it ce-provision-config, leave it private and do not create a README

At this point you should have a new repository at https://gitlab.controller.acme.com/core/ce-provision-config (obviously with your controller server URL, not our example one).

Configure the controller user's key in GitLab

  1. Back in your server, grab the public part of your controller user's SSH key pair: cat .ssh/id_ed25519.pub
  2. Copy the resulting line to your clipboard and go back to GitLab in your browser (tip: usually clicking three times selects the line)
  3. Click on the Admin button in the bottom left corner
  4. In the left-hand admin menu click on Deploy keys then the New deploy key button
  5. Create your key with these values and click Create:
    • Title: [email protected] (changing hostname of course)
    • Key: paste the public key from the server in here
    • Expiration date: blank
  6. Go back to your repository, e.g. https://gitlab.controller.acme.com/core/ce-provision-config
  7. On the left-hand Project menu click Settings -> Repository
  8. Expand the Deploy keys section, click Publicly accessible deploy keys and click Enable against your new key
  9. Go to Enabled deploy keys in the same dialogue and click the little pencil icon to edit
  10. Tick Grant write permissions to this key and click Save changes

Set up and push your ce-provision-config repository

  1. Go back to your repository again in GitLab, click the blue Code button and copy the Clone with SSH value
  2. Back on your server, change to the directory where the example ce-provision-config was installed: cd ce-provision/config
  3. Execute the following commands to sort out your Git repository configuration:
# move the example repo out of the way
git remote rename origin example
# add a new remote for our new repo - use your URL from step 1!
git remote add origin [email protected]:core/ce-provision-config.git
# push our changes - you will need to confirm the connection by typing 'yes'
git push origin 2.x

Returning to your repository in GitLab, e.g. https://gitlab.controller.acme.com/core/ce-provision-config, you will now see your own ce-provision-config repository, which you can now control and edit with the settings you need for ce-provision in your infra.

Because we set up GitLab CI in the example repository for you, you should see YAML linting builds happening already in your repo under Build -> Pipelines.

Configure your config to use itself

In your repository browse to hosts -> group_vars -> all and click on the file ce_provision.yml. It will look something like this:

ce_provision:
  own_repository: https://github.com/codeenigma/ce-provision.git
  own_repository_branch: 2.x
  # Once you have created your own config repo using this as a base, update this URL.
  config_repository: https://github.com/codeenigma/ce-provision-config-example.git
  config_repository_branch: 2.x
  username: controller
  local_dir: /home/controller/ce-provision
  groups:
    - bypass2fa

As the comment states, you need to update the config_repository variable with the value you copied to your clipboard in step 1 of the previous section, the Git URL to your repository. Click the blue Edit button thenEdit single file and you can change the file, for example:

ce_provision:
  own_repository: https://github.com/codeenigma/ce-provision.git
  own_repository_branch: 2.x
  config_repository: [email protected]:core/ce-provision-config.git
  config_repository_branch: 2.x
  username: controller
  local_dir: /home/controller/ce-provision
  groups:
    - bypass2fa

Once you file looks like the above, click the Commit changes button under the editor and return to your server. You should already be in the right place, so just run this command to fetch your change: git pull origin 2.x

Saving your runner in code

At this point you can optionally save your runner into your Ansible code at hosts/group_vars/_controller/gitlab_runner.yml something like this:

gitlab_runner:
  username: "{{ ce_provision.username }}"
  runner_workingdir: "/home/{{ ce_provision.username }}/build"
  runners:
    # Default built-in shell executor runner
    - output_limit: 30000
      name: "Default shell runner"
      url: "https://gitlab.controller.acme.com"
      token: "<VALUE IN YOUR CONFIG FILE ON THE SERVER>"
      executor: "shell"

ce-provision-config files to check

There are a number of example files in hosts that should usually be updated before you continue. The easiest way to do this is to open the project in GitLab, click the Edit button and select Web IDE. This will open the GitLab IDE (editor) in a new window. You can browse to that folder in the IDE using the directory tree on the left.

hosts/hosts.yml

You must add your controller server's fully qualified domain name (FQDN) where it says controller.acme.com.

Debian packages

These files should be checked by everybody.

hosts/group_vars/all/clamav.yml

To receive email reports of detected issues you should change the email addresses in this config.

hosts/group_vars/all/firewall_config.yml

There are a number of example rules that have the IP address set to X.X.X.X. They all need to receive proper IP addresses before being used (none are actively used out of the box).

Most critically, you should edit the ssh_restricted firewall ruleset to restrict access to your servers over SSH. There is an example ruleset with the IP address set to X.X.X.X which will need to be a proper IP address before you can use this ruleset. Once you've done this, you should also edit the firewall rules in place in the hosts/group_vars/_web/firewall_config.yml file to use ssh_restricted instead of ssh_open.

hosts/group_vars/all/openvpn_config.yml

This only applies if you decide to run a VPN server using our OpenVPN role, if not you can simply delete this file. You should change the certificate details under certs, the org, email, etc.

hosts/group_vars/all/rkhunter.yml

To receive email reports of detected issues you should change the email addresses in this config.

hosts/group_vars/all/user_provision.yml

The ssh_keys variable will be a list of the controller's public keys to place on each target server. Usually there will be a single one and because the installer script sets the controller node up as localhost the path should work fine, however once you have built the server again using a GitLab pipeline (see below) then a second path will be added with your FQDN within. So do verify the path in the lookup() filter in this file really points to the correct SSH public key and correct if necessary, or other machine builds will fail.

AWS

These files only impact AWS users.

hosts/group_vars/_controller/aws_credentials.yml

Important - consider setting up SOPS to encrypt secrets before proceeding with entering them into your repository. If you have AWS CLI profiles ready to configure you can add them to this file following the role documentation.

hosts/group_vars/all/_aws_infra_name.yml

This only applies if you are using AWS. You can either delete this file completed and pass _infra_name as an extra variable to ce-provision at runtime, or set it to the name of your infra if your intention is to control a single infrastructure with your controller.

hosts/group_vars/all/_aws_security_groups.yml

As with firewall config below, there are a few of example custom rules that have the IP address set to X.X.X.X. They all need to receive proper IP addresses before being used (none are actively used out of the box).

hosts/group_vars/all/_aws_sns.yml

This only applies if you are using AWS services. You should set the email address(es) you would like service alert notifications to go to in the AWS SNS variables under subscriptions - an example is provided. You should also set sns: true to receive alerts as it is false by default.

hosts/group_vars/all/aws_acl.yml

The default ACL protection for AWS Web Application Firewall (WAF) used with Application Load Balancers (ALBs) and CloudFront. You can optionally add rules for your infrastructure's protection to this file.

hosts/group_vars/all/aws_backup.yml

This only applies if you are using AWS and wish to use the AWS Backup service. We set the off-site backup region to eu-central-1 by default. If you want to back up to another region, change the aws_backup.copy_vault.region variable in this file. Delete the copy_vault dictionary entirely if you do not want off-site backups at all.

hosts/group_vars/all/nginx.yml

If you want to ship NGINX logs to AWS CloudWatch, uncomment the log settings in this file.

Build your server from GitLab

At this point you should be ready to build your controller server using ce-provision in GitLab:

  1. In your repository, click Build -> Pipelines on the left-hand menu (there should already be some green 'lint' builds in there)
  2. Click New pipeline in the top right
    • The defaults should be already set up for your controller, as long as you have carefully checked all the above files
  3. Enter the fully qualified domain name (FQDN), e.g. controller.acme.com, in the RESOURCE box and click New pipeline at the bottom
    • For this kind of build, and if you're not using AWS anyway, REGION can be disregarded

Your build will start and should succeed.

Future changes

From now on you can change your variables for all servers in the hosts/group_vars/all directory and your variables that will only affect this controller in hosts/group_vars/_controller. You can build your controller any time by putting the FQDN of the server into the RESOURCE box when you run a pipeline.

Have a look at the basic usage section to continue your journey.

Home

Quick start

Advanced

Clone this wiki locally