Cloud Foundry Management (cf-mgmt)

Go automation for managing orgs, spaces, users (from ldap groups or internal store) mapping to roles, quotas, application security groups and private-domains that can be driven from concourse pipeline and GIT managed metadata

Maintainer

• Caleb Washburn

Support

cf-mgmt is a community supported cloud foundry add-on. Opening issues for questions, feature requests and/or bugs is the best path to getting "support". We strive to be active in keeping this tool working and meeting your needs in a timely fashion.

Install

Compiled releases are available on Github. Download the binary for your platform and place it somewhere on your path. Don't forget to chmod +x the file on Linux and macOS.

Alternatively, you may wish to build from source.

Build from the source

cf-mgmt is written in Go. To build the binary yourself, follow these steps:

• Install Go.
• Install Glide, a dependency management tool for Go.
• Clone the repo:
  • mkdir -p $(go env GOPATH)/src/github.com/pivotalservices
  • cd $(go env GOPATH)/src/github.com/pivotalservices
  • git clone [email protected]:pivotalservices/cf-mgmt.git
• Install dependencies:
  • cd cf-mgmt
  • glide install
  • go build

To cross compile, set the $GOOS and $GOARCH environment variables. For example: GOOS=linux GOARCH=amd64 go build.

Testing

To run the unit tests, use go test $(glide nv).

Integration tests

There are integration tests that require some additional configuration.

The LDAP tests require an LDAP server, which can be started with Docker:

docker pull cwashburn/ldap
docker run -d -p 389:389 --name ldap -t cwashburn/ldap
RUN_INTEGRATION_TESTS=true go test ./ldap/...

The remaining integration tests require PCF Dev to be running.

cf dev start
uaac target uaa.local.pcfdev.io
uaac token client get admin -s admin-client-secret
uaac client add cf-mgmt \
  --name cf-mgmt \
  --secret cf-mgmt-secret \
  --authorized_grant_types client_credentials,refresh_token \
  --authorities cloud_controller.admin,scim.read,scim.write
RUN_INTEGRATION_TESTS=true go test ./integration/...

Code Generation

Some portions of this code are autogenerated. To regenerate them, install the prerequisites:

• go get -u github.com/jteeuwen/go-bindata
• go get -u github.com/golang/mock/mockgen

And then run go generate $(glide nv) from the project directory, or go generate . from a specific directory.

Contributing

PRs are always welcome or open issues if you are experiencing an issue and will do my best to address issues in timely fashion.

The following operation are enabled with cf-mgmt for helping to manage your configuration

init-config

This command will initialize a folder structure to add a ldap.yml and orgs.yml file. This should be where you start to leverage cf-mgmt. If your foundation is ldap enabled you can specify the ldap configuration info in ldap.yml otherwise you can disable this feature by setting the flag to false.

USAGE:
   cf-mgmt init-config [command options] [arguments...]

DESCRIPTION:
   initializes folder structure for configuration

OPTIONS:
   --config-dir value  config dir.  Default is config [$CONFIG_DIR]

add-org-to-config

This will add the specified org to orgs.yml and create folder based on the org name you specified. Within this folder will be an orgConfig.yml and spaces.yml which will be empty but will eventually contain a list of spaces. Any org listed in orgs.yml will be created when the create-orgs operation is ran.

org: test

# added in 0.0.63+ which will remove spaces not configured in cf-mgmt
enable-delete-spaces: true
spaces:
  - space1
  - space2

orgConfig.yml allows specifying for the following:

• what groups to map to org roles (OrgManager, OrgBillingManager, OrgAuditor)
• setting up quotas for the org

USAGE:
   cf-mgmt add-org-to-config [command options] [arguments...]

DESCRIPTION:
   adds specified org to configuration

OPTIONS:
   --org value         org name to add [$ORG]
   --config-dir value  config dir.  Default is config [$CONFIG_DIR]

add-space-to-config

This command allows for adding a space to a previously defined org. This will generate a folder for each space inside the orgs folder. In the spaces folder will contain a spaceConfig.yml and a security-group.json file. Any space listed in spaces.yml will be created when the create-spaces operation is ran. The spaceConfig.yml allows for specifying the following:

• allow ssh at space level
• map ldap group names to SpaceDeveloper, SpaceManager, SpaceAuditor role
• setup quotas at a space level (if enabled)
• apply application security group config at space level (if enabled)

USAGE:
   cf-mgmt add-space-to-config [command options] [arguments...]

DESCRIPTION:
   adds specified space to configuration for org

OPTIONS:
   --config-dir value  config dir.  Default is config [$CONFIG_DIR]
   --org value         org name of space [$ORG]
   --space value       space name to add [$SPACE]

export-config

This command will export org/space/user details from an existing Cloud Foundry instance. This is useful when you have an existing foundation and would like to use the cf-mgmt git workflow to create org and space details to a different foundation.

Once your run ./cf-mgmt export-config, a config directory with org and space details will be created. This will also export user details such as org and space users and their roles within specific org and space. Other details exported include org and space quota details and ssh access at space level.

You can exclude orgs and spaces from export by using the flag --excluded-org and for space --excluded-space.

WARNING : Running this command will delete existing config folder and will create it again with the new configuration

NOTE: Please make sure to enable and configure LDAP after export. Otherwise when the pipeline runs, it will un map the user roles assuming that they don't exists in LDAP

Command usage:

USAGE:
   cf-mgmt export-config [command options] [arguments...]

DESCRIPTION:
   Exports org and space configurations from an existing Cloud Foundry instance. [Warning: This operation will delete existing config folder]

OPTIONS:
   --system-domain value   system domain [$SYSTEM_DOMAIN]
   --user-id value         user id that has admin privileges [$USER_ID]
   --password value        password for user account that has admin privileges [$PASSWORD]
   --client-secret value   secret for user account that has admin privileges [$CLIENT_SECRET]
   --config-dir value      config dir.  Default is config [$CONFIG_DIR]
   --excluded-org value    Org to be excluded from export. Repeat the flag to specify multiple orgs
   --excluded-space value  Space to be excluded from export. Repeat the flag to specify multiple spaces

Of the above ,

--system-domain value   system domain [$SYSTEM_DOMAIN]
--user-id value         user id that has admin privileges [$USER_ID]
--password value        password for user account that has admin privileges [$PASSWORD]
--client-secret value   secret for user account that has admin privileges [$CLIENT_SECRET]

are required options.

Configuration

After running the above commands, there will be a config directory in the working directory. This will have a folder per org and within each org there will be a folder for each space.

├── ldap.yml
├── orgs.yml
├── test
│   ├── orgConfig.yml
│   ├── space1
│   │   ├── security-group.json
│   │   └── spaceConfig.yml
│   └── spaces.yml
└── test2
    ├── orgConfig.yml
    ├── space1a
    │   ├── security-group.json
    │   └── spaceConfig.yml
    └── spaces.yml

Org Configuration

There is a orgs.yml that contains list of orgs that will be created. This should have a corresponding folder with name of the orgs cf-mgmt is managing. orgs.yml also can be configured with a list of protected orgs which would never be deleted when using the the delete-orgs command. An example of how orgs.yml could be configured is seen below.

orgs:
- foo-org
- bar-org
# added in 0.0.63+ which will remove orgs not configured in cf-mgmt
enable-delete-orgs: true
# added in 0.0.63+ which allows configuration of orgs to 'ignore'
protected_orgs:
- system
- p-spring-cloud-services

This will contain a orgConfig.yml and folder for each space. Each orgConfig.yml consists of the following.

# org name
org: test

org-billingmanager:
  # list of ldap users that will be created in cf and given billing manager role
  ldap_users:
    - cwashburn1
    - cwashburn2

  # list of users that would be given billing manager role (must already be a user created via cf create-user)
  users:
    - [email protected]
    - [email protected]


  # ldap group that contains users that will be added to cf and given billing manager role
  ldap_group: test_billing_managers

  # added in 0.0.62+ which will allow configuration of a list of groups works with ldap_group
  ldap_groups:
    - test_billing_managers_2

  # added in 0.0.66+ which will allow configuration of a list of saml user email addresses
  saml_users:
    - [email protected]
    - [email protected]
org-manager:
  # list of ldap users that will be created in cf and given org manager role
  ldap_users:
    - cwashburn1
    - cwashburn2

  # list of users that would be given org manager role (must already be a user created via cf create-user)
  users:
    - [email protected]
    - [email protected]

  # ldap group that contains users that will be added to cf and given org manager role
  ldap_group: test_org_managers

  # added in 0.0.62+ which will allow configuration of a list of groups works with ldap_group
  ldap_groups:
    - test_org_managers_2

  # added in 0.0.66+ which will allow configuration of a list of saml user email addresses
  saml_users:
    - [email protected]
    - [email protected]
org-auditor:
  # list of ldap users that will be created in cf and given org manager role
  ldap_users:
    - cwashburn1
    - cwashburn2

  # list of users that would be given org auditor role (must already be a user created via cf create-user)
  users:
    - [email protected]
    - [email protected]

  # ldap group that contains users that will be added to cf and given org auditor role
  ldap_group: test_org_auditors

  # added in 0.0.62+ which will allow configuration of a list of groups works with ldap_group
  ldap_groups:
    - test_org_auditors_2

  # added in 0.0.66+ which will allow configuration of a list of saml user email addresses
  saml_users:
    - [email protected]
    - [email protected]
# if you wish to enable custom org quotas
enable-org-quota: true
# 10 GB limit
memory-limit: 10240
# unlimited
instance-memory-limit: -1
total-routes: 10
# unlimited
total-services: -1
paid-service-plans-allowed: true

# added in 0.0.48+ which will remove users from roles if not configured in cf-mgmt
enable-remove-users: true/false

# added in 0.0.64+ which will remove users from roles if not configured in cf-mgmt
private-domains: ["test.com", "test2.com"]
enable-remove-private-domains: true/false

Space Configuration

There will be a spaces.yml that will list all the spaces for each org. There will also be a folder for each space with the same name. Each folder will contain a spaceConfig.yml and security-group.json file with an empty json file. Each spaceConfig.yml will have the following configuration options:

# org that is space belongs to
org: test

# space name
space: space1

# if cf ssh is allowed for space
allow-ssh: yes

space-manager:
  # list of ldap users that will be created in cf and given space manager role
  ldap_users:
    - cwashburn1
    - cwashburn2

  # list of users that would be given space manager role (must already be a user created via cf create-user)
  users:
    - [email protected]
    - [email protected]

  # ldap group that contains users that will be added to cf and given space manager role
  ldap_group: test_space1_managers

  # added in 0.0.62+ which will allow configuration of a list of groups works with ldap_group
  ldap_groups:
    - test_space1_managers_2

  # added in 0.0.66+ which will allow configuration of a list of saml user email addresses
  saml_users:
    - [email protected]
    - [email protected]
space-auditor:
  # list of ldap users that will be created in cf and given space auditor role
  ldap_users:
    - cwashburn1
    - cwashburn2

  # list of users that would be given space auditor role (must already be a user created via cf create-user)
  users:
    - [email protected]
    - [email protected]

  # ldap group that contains users that will be added to cf and given space auditor role
  ldap_group: test_space1_auditors

  # added in 0.0.62+ which will allow configuration of a list of groups works with ldap_group
  ldap_groups:
    - test_space1_auditors_2

  # added in 0.0.66+ which will allow configuration of a list of saml user email addresses
  saml_users:
    - [email protected]
    - [email protected]

space-developer:
  # list of ldap users that will be created in cf and given space developer role
  ldap_users:
    - cwashburn1
    - cwashburn2

  # list of users that would be given space developer role (must already be a user created via cf create-user)
  users:
    - [email protected]
    - [email protected]

  # ldap group that contains users that will be added to cf and given space developer role
  ldap_group: test_space1_developers

  # added in 0.0.62+ which will allow configuration of a list of groups works with ldap_group
  ldap_groups:
    - test_space1_developers_2

  # added in 0.0.66+ which will allow configuration of a list of saml user email addresses
  saml_users:
    - [email protected]
    - [email protected]
# to enable custom quota at space level  
enable-space-quota: true
# 10 GB limit
memory-limit: 10240
# unlimited
instance-memory-limit: -1
total-routes: 10
# unlimited
total-services: -1
paid-service-plans-allowed: true

# to enable custom asg for the space.  If true will deploy asg defined in security-group.json within space folder
enable-security-group: false

# added in 0.0.48+ which will remove users from roles if not configured in cf-mgmt
enable-remove-users: true/false

LDAP Configuration

LDAP configuration file ldap.yml is located under the config folder. By default, LDAP is disabled and you can enable it by setting enabled: true. Once this is enabled, all other LDAP configuration properties are required.

SAML Configuration with ldap group lookups

LDAP configuration file ldap.yml is located under the config folder. To have cf-mgmt create SAML users in UAA need to enable ldap to lookup the user information from an LDAP source to properly create the SAML users. In orgConfig.yml and spaceConfig.yml leverage either/or ldap_users or ldap_group(s)

enabled: true
ldapHost: 127.0.0.1
ldapPort: 10389
bindDN: uid=admin,ou=system
userSearchBase: ou=users,dc=example,dc=com
userNameAttribute: uid
userMailAttribute: mail
groupSearchBase: ou=groups,dc=example,dc=com
groupAttribute: member
origin: <needs to match origin configured for elastic runtime>

SAML Configuration

LDAP configuration file ldap.yml is located under the config folder. To have cf-mgmt create SAML users you can disable ldap integration for looking up users in ldap groups with v0.0.66+ as orgConfig.yml and spaceConfig.yml now includes a saml_users array attribute which can contain a list of email addresses.

enabled: false
origin: <needs to match origin configured for elastic runtime>
ldapHost:
ldapPort: 389
bindDN:
userSearchBase:
userNameAttribute:
userMailAttribute:
groupSearchBase:
groupAttribute:

Features

• Removing users from cf that are not in cf-mgmt metadata was added in 0.48+ release. This is an opt-in feature for existing cf-mgmt users at an org and space config level. For any new orgs/config created with cf-mgmt cli 0.48+ it will default this parameter to true. To opt-in ensure you are using latest cf-mgmt version when running pipeline and add enable-remove-users: true to your configuration.

• Removing orgs and spaces from cf that are not in cf-mgmt metadata was added in 0.0.63+ release. This is an opt-in feature for existing cf-mgmt users at an org and space config level. For any new orgs/config created with cf-mgmt cli 0.0.63+ it will default this parameter to true. To opt-in ensure you are using latest cf-mgmt version when running pipeline and add enable-delete-orgs: true or enable-delete-spaces: true to your configuration.

• Managing private domains at org level was added with 0.0.64+. This requires you to update concourse pipeline to to invoke create-org-private-domains command. By default enable-remove-private-domains: true is set for any new orgs created with 0.0.64+ cli. This will remove any private domains for that org that are not in array of private domain names.

Recommended workflow

Operations team can setup a a git repo seeded with cf-mgmt configuration. This will be linked to a concourse pipeline (example pipeline generated below) that will create orgs, spaces, map users, create quotas, deploy ASGs based on changes to git repo. Consumers of this can submit a pull request via GIT to the ops team with comments like any other commit. This will create a complete audit log of who requested this and who approved within GIT history. Once PR accepted then concourse will provision the new items.

Generate Concourse Pipeline

This will generate a pipeline.yml, vars.yml and necessary task yml files for running all the tasks listed below. Just need to update your vars.yml and check in all your code to GIT and execute the fly command to register your pipeline. vars.yml contains place holders for LDAP and CF user credentials. If you do not prefer storing the credentials in vars.yml, you can pass them via the fly command line arguments.

USAGE:
   cf-mgmt generate-concourse-pipeline [arguments...]

DESCRIPTION:
   generate-concourse-pipeline   

Once the pipeline files are generated, you can create a pipeline as follows:

fly -t  login -c <concourse_instance>
fly -t <targetname> set-pipeline -p <pipeline_name> -c pipeline.yml -l vars.yml —-var "ldap_password=<ldap_password>" --var "client_secret=<client_sercret>" —-var "password=<org/space_admin_password>"

If both vars.yml and --var are specified, --vars values takes precedence.

The following operation are enabled with cf-mgmt that will leverage configuration to modify your Cloud Foundry installation

To execute any of the following you will need to provide:

• user id that has privileges to create/update/delete users, orgs and spaces. This user doesn't have to be an admin user. Assuming you have Cloud Foundry UAA Client installed, you can create a non-admin user with just enough privileges in the following way:

$ uaac target uaa.<system-domain>
$ uaac token client get <adminuserid> -s admin-client-secret

$ uaac client add cf-mgmt \
  --name cf-mgmt \
  --secret cf-mgmt-secret \
  --authorized_grant_types client_credentials,refresh_token \
  --authorities cloud_controller.admin,scim.read,scim.write

As you can see, cloud_controller.admin,scim.read,scim.write gives this user just enough rights to add/update/delete users, orgs and space and still being a non-admin user. Learn more about the scopes authorized by UAA at UAA Scopes

• password , an optional password for the above user
• uaac client secret for the above user (assumes the same user account for cf commands is used)
• system domain name of your foundation

create-orgs

• creates orgs specified in orgs.yml

delete-orgs

• deletes orgs NOT specified in orgs.yml. This is recursive for underlaying spaces and apps.
• Will NOT delete orgs which are protected_orgs in orgs.yml
• specifying --peek will show you which orgs would be deleted, without actually deleting them.

create-org-private-domains

• creates an private domains for a given org based on private-domains configured in orgConfig.yml
• Will delete any private domains not in private-domains for a given org if enable-remove-private-domains is set to true

update-org-quotas

• updates org quotas specified in orgConfig.yml

update-org-users

• syncs users from ldap groups configured in orgConfig.yml assuming that ldap.yml is configured

create-spaces

• creates spaces for all spaces listed in each spaces.yml

delete-spaces

• deletes spaces NOT specified in spaces.yml. This is recursive delete apps, brokers, etc for a space.
• specifying --peek will show you which spaces would be deleted, without actually deleting them.

update-spaces

• updates allow ssh into space property

update-space-quotas

• creates/updates quota for a given space

update-space-users

• syncs users from ldap groups configured in spaceConfig.yml assuming that ldap.yml is configured

update-space-security-groups

• creates/updates application security groups for a given space