{"id":19040949,"url":"https://github.com/cloudfoundry/go-cf-api","last_synced_at":"2025-04-17T17:31:02.313Z","repository":{"id":40261334,"uuid":"433836463","full_name":"cloudfoundry/go-cf-api","owner":"cloudfoundry","description":"A proof of concept implementation as an alternative to cloud_controller_ng, written in Go.","archived":true,"fork":false,"pushed_at":"2023-01-07T15:46:10.000Z","size":72946,"stargazers_count":5,"open_issues_count":15,"forks_count":1,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-01-18T00:13:24.131Z","etag":null,"topics":["api","cloudfoundry","golang"],"latest_commit_sha":null,"homepage":"https://cloudfoundry.github.io/go-cf-api/","language":"PLpgSQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudfoundry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-12-01T13:23:41.000Z","updated_at":"2024-09-24T18:01:09.000Z","dependencies_parsed_at":"2023-02-07T14:00:45.447Z","dependency_job_id":null,"html_url":"https://github.com/cloudfoundry/go-cf-api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry%2Fgo-cf-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry%2Fgo-cf-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry%2Fgo-cf-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry%2Fgo-cf-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudfoundry","download_url":"https://codeload.github.com/cloudfoundry/go-cf-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249359885,"owners_count":21257123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","cloudfoundry","golang"],"created_at":"2024-11-08T22:26:15.703Z","updated_at":"2025-04-17T17:30:57.300Z","avatar_url":"https://github.com/cloudfoundry.png","language":"PLpgSQL","readme":"[![CodeGen](https://github.com/cloudfoundry/go-cf-api/actions/workflows/code-gen.yml/badge.svg)](https://github.com/cloudfoundry/go-cf-api/actions/workflows/code-gen.yml)\n[![Build Documentation](https://github.com/cloudfoundry/go-cf-api/actions/workflows/build-docs.yml/badge.svg)](https://github.com/cloudfoundry/go-cf-api/actions/workflows/build-docs.yml)\n[![Deploy Documentation](https://github.com/cloudfoundry/go-cf-api/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/cloudfoundry/go-cf-api/actions/workflows/deploy-docs.yml)\n\n[![Build Binaries](https://github.com/cloudfoundry/go-cf-api/actions/workflows/build-binaries.yml/badge.svg)](https://github.com/cloudfoundry/go-cf-api/actions/workflows/build-binaries.yml)\n[![Integration Tests](https://github.com/cloudfoundry/go-cf-api/actions/workflows/integration-tests.yml/badge.svg)](https://github.com/cloudfoundry/go-cf-api/actions/workflows/integration-tests.yml)\n[![Unit Tests](https://github.com/cloudfoundry/go-cf-api/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/cloudfoundry/go-cf-api/actions/workflows/unit-tests.yml)\n\n[![Linter](https://github.com/cloudfoundry/go-cf-api/actions/workflows/lint.yml/badge.svg)](https://github.com/cloudfoundry/go-cf-api/actions/workflows/lint.yml)\n[![CodeQL Analyze](https://github.com/cloudfoundry/go-cf-api/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/cloudfoundry/go-cf-api/actions/workflows/codeql-analysis.yml)\n\n\n# go-cf-api\nA **proof of concept implementation** as an alternative to [cloud_controller_ng](https://github.com/cloudfoundry/cloud_controller_ng), written in Go.\\\nCurrently, this project is intended to be deployed alongside the existing `cloud_controller_ng` with a L7 router to forward requests to endpoints that have been completed to the Go implementation (based on both path and HTTP method). A deployment using this setup should pass [CATS](https://github.com/cloudfoundry/cf-acceptance-tests).\n\u003e Since this project only implements a subset of the CF API endpoints, it should not be deployed standalone.\n\n## Deploying with cf-deployment\nSee the [ADR](https://cloudfoundry.github.io/go-cf-api/adrs/ADR%20-%20Traffic%20Splitter#decision-outcome) for more information on this deployment approach.\n\nTo deploy `go-cf-api` into a [cf-deployment](https://github.com/cloudfoundry/cf-deployment), include\n[this ops file](https://github.com/cloudfoundry-incubator/cf-performance-tests-pipeline/blob/main/operations/deploy-go-cf-api.yml).\nThis will use [HAProxy](https://github.com/cloudfoundry/haproxy-boshrelease) to route all requests to the `go-cf-api` where that endpoint and method has been implemented.\nAny endpoints that are not yet implemented by `go-cf-api` will continue to be served by [cloud_controller_ng](https://github.com/cloudfoundry/cloud_controller_ng).\n### Links\n\n- [Documentation](https://cloudfoundry.github.io/go-cf-api/)\n- [BOSH Release](https://github.com/cloudfoundry/go-cf-api-release)\n- [Opsfile for cf-deployment](https://github.com/cloudfoundry-incubator/cf-performance-tests-pipeline/blob/main/operations/deploy-gontroller.yml)\n\n## Development Setup\n### Requirements\n- [Go](https://golang.org/dl) version 1.17\n- [Mage](https://github.com/magefile/mage) (Makefile alternative in go) - `go install github.com/magefile/mage`\n- [Mysql](https://mariadb.com/kb/en/mysql-command-line-client/) and [Postgres](https://www.postgresql.org/docs/13/app-psql.html) CLI Tools (mysql, mysqldump, psql, pgdump etc.)\n- Additional tooling/CLIs - `mage GetDependencies`\n#### Optional\n- [NodeJS](https://nodejs.org/en/) and [Yarn](https://yarnpkg.com/) (for working with the documentation in /docs)\n- [Git LFS](https://git-lfs.github.com/) (to get assets resolved in /docs)\n- [Docker + docker-compose](https://www.docker.com/) for running additional runtime dependencies\n\n## Prepare dev database\nTo run go-cf-api requires a migrated/existing Cloud Controller database.\nTo help with this, there is a [docker-compose.yml](https://github.com/cloudfoundry/go-cf-api/blob/main/docker-compose.yml) file to start the DB instances and [SQL dumps](https://github.com/cloudfoundry/go-cf-api/blob/main/database_dumps) from an existing `cloud_controller_ng` that can be imported to create a DB for testing.\n\n\u003e There are `mage` commands for performing most common database operations. Run `mage help` to see the full list of available commands.\n\nFirst start needed runtime components with:\n```bash\ndocker compose up -d\n\n[+] Running 3/0\n ⠿ Container go-cf-api_mariadb_1   Running                                                                                                                                                                                                                                                                   0.0s\n ⠿ Container go-cf-api_postgres_1  Running                                                                                                                                                                                                                                                                   0.0s\n ⠿ Container go-cf-api_uaa_1       Running\n```\nTo ensure the DB is ready for use, it needs creating and loading with the relevant database dump.\n### Postgres\n```bash\nmage DBCreate config_psql.yaml\nmage DBLoad config_psql.yaml database_dumps/3.102.0_psql_ccdb.sql\n```\n\n### MySQL/MariaDB\n```bash\nmage DBCreate config_mysql.yaml\nmage DBLoad config_mysql.yaml database_dumps/3.102.0_mysql_ccdb.sql\n```\n\n### Useful database operations\n* Drop database\n\t```bash\n\tmage DBDelete config_psql.yaml\n\t```\n* Drop and create database and import new dump\n\t```bash\n\tmage DBRecreate config_psql.yaml database_dumps/3.102.0_psql_ccdb.sql\n\t```\n\n## Running commands\nDifferent database code and types of test are conditionally compiled and run based on [Go build tags](https://pkg.go.dev/cmd/go#hdr-Build_constraints).\n\nTo target a specific database and/or test set, use:\n```\ngo -tags=psql,unit \u003cgo command\u003e\n```\n\nTo avoid having to type out tags every time, you can instead run:\n```\nexport GOFLAGS=\"-tags=psql,unit\"\n```\n\nThis will make `go test ./...` just run the unit tests and also allow you to just run `go run cmd/main.go config_psql.yaml`\n\nAvailable Tags are:\n- mysql (adds mysql database support)\n- psql (adds psql database support)\n- unit (includes unittests)\n- integration (includes integration tests)\n\nNote here that you can build/run go-cf-api just with either `mysql` or `psql` support/tag.\nThe intended way to support both dbs is to build two separate binaries and depending on the backend use the fitting one.\nThe `unit` and `integration` tags are just relevant for running `go test` but either `mysql` or `psql` must be always provided otherwise there are missing imports.\n\n## Starting the go-cf-api\n* Postgres\n\t```bash\n\tgo run --tags=psql cmd/main.go config_psql.yaml\n\t```\n* MySQL/MariaDB\n\t```bash\n\tgo run --tags=mysql cmd/main.go config_mysql.yaml\n\t```\n\nThe default values in the `config_{db}.yml` and `sqlboiler_{db}.toml` files should match the credentials for each database in `docker-compose.yml`.\nYou may need to modify these credentials to connect to an alternative DB setup.\n\nThe API should be accessible at\n```\nhttp://localhost:8080/v3\n```\n\nThe API Documentation should be accessible at\n```\nhttp://localhost:8080/docs/v3\n```\n\n## Building the go-cf-api binaries\n\nThe two binaries (for `psql` and `mysql`) can then be compiled for your current OS/architecture with:\n```bash\nmage build\n```\nBinaries are output to the `/build` directory.\n\nThe binaries can be compiled for other architectures by exporting the `GOOS` and `GOARCH` environment variables.\n\n## List of API endpoints\nFollowing endpoints have implemented and should be equivalent to the endpoints from `cloud_controller_ng`.\n\n#### go-cf-api Specific Endpoints\n- http://localhost:8080/healhz (Health Endpoint)\n- http://localhost:8080/metrics (Prometheus Metrics)\n- http://localhost:8080/docs/v3 (API Documentation)\n#### V3 API\n- http://localhost:8080/\n- http://localhost:8080/v3\n- http://localhost:8080/v3/info\n- http://localhost:8080/v3/buildpacks (GET)\n- http://localhost:8080/v3/buildpacks/:guid (GET, POST)\n- http://localhost:8080/v3/security_groups (GET)\n- http://localhost:8080/v3/security_groups/:guid (GET)\n\n\n## Querying locally\nTo query most endpoints locally, you will need a JWT. The easiest way to get this is to create a UAA client with the [uaac](https://github.com/cloudfoundry/cf-uaac) CLI then login with then `cf` CLI. To create a user called `bob`:\n```bash\nuaac target http://localhost:8095\nuaac token client get admin -s adminsecret\nuaac user add bob -p password --emails none@none.local\ncf api http://localhost:8080\ncf auth bob password\n```\n\nNow various endpoints can be queried using e.g. `cf curl /v3/buildpacks`\n\nTo authenticate as admin (for example to assign roles to `bob`):\n```bash\ncf auth admin adminsecret --client-credentials\n```\n\n## Documentation\n\nThe documentation is based on [docusaurus](https://docusaurus.io/) and can be found at https://pages.github.com/cloudfoundry/go-cf-api/.\nIt is defined under `/docs` in this project and is then served by github-pages from the `gh-pages` branch which is detached from the other branches.\nA GitHub workflow ensures the `gh-pages` branch always reflects the state of the main branch's `/docs` folder.\n\nPackage documentation is auto generated using [gomarkdoc](https://github.com/princjef/gomarkdoc) and integrated into [docusaurus](https://docusaurus.io/), as is the API documentation which is generated from code comments via [swag](https://github.com/swaggo/swag).\nAdditionally, the `go-cf-api` binaries/`go run cmd/main.go` will also serve the versioned API documentation in a Swagger UI at:\n```\nhttp://localhost:8080/docs/v3\n```\n\nSome manual documentation such as project ADRs (architecture decision records) are included under `/doc/adrs` and `/docs/docs`.\nThe `/docs/docs/intro.md` file is a symlink to this `README.md`.\nFor further information how to build the documentation locally refer to the [Docs README](https://github.com/cloudfoundry/go-cf-api/blob/main/docs/README.md)\n\n## Development tasks\n\nBelow is a summary of the most important development workflows and tools.\n\n### Generating DB models\nTo support different databases (Postgres and MySQL/MariaDB), we generate two sets of database models with [sqlboiler](https://github.com/volatiletech/sqlboiler).\nThese are then included in the same package and given build tag comments to control when to compile each model set into the binary.\nTwo binaries are then produced - one for each database.\nAttempting to use e.g. the `mysql` binary on a Postgres database will result in a startup error.\n\nTo facilitate the generating, combining and build tagging of the `sqlboiler` models, there is a mage task to automate it.\nFirstly one must have a `mysql` and `psql` instance running with a desired database schema already on them(in the `ccdb` database). Then one can run:\n```bash\nmage GenerateSQLBoiler\n```\nThis will scan both databases schemas and generate go code to `/internal/sotrage/db/models/` as well as add the relevant build tag comments to compile the correct models for each supported DB.\n\n### Running the linter\nThis project uses [golangci-lint](https://golangci-lint.run/) to ensure code is formatted correctly and return values are checked etc.\nTo run the linter, run:\n```\ngolangci-lint run --build-tags psql,unit,integration\n```\n\nThere is a GitHub Action that runs the linter on every push. No code should be merged until it passes all the linter checks.\n\n### Running tests\nDifferent tags are used to control which tests are run:\n* Unit tests\n\t```bash\n\tgo test -tags=\"unit,psql\" ./...\n\t```\n* Integration tests (Postgres) - require running database\n\t```bash\n\tgo test -tags=integration,psql -parallel=1 -p=1 ./... -args $PWD/config_psql.yaml\n\t```\n* Integration tests (MySQL/MariaDB) - require running database\n\t```bash\n\tgo test -tags=integration,mysql -parallel=1 -p=1 ./... -args $PWD/config_mysql.yaml\n\t```","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudfoundry%2Fgo-cf-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudfoundry%2Fgo-cf-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudfoundry%2Fgo-cf-api/lists"}