{"id":24994966,"url":"https://github.com/byrongomezjr/kubernetes-api","last_synced_at":"2026-04-11T00:13:48.450Z","repository":{"id":275679162,"uuid":"926824266","full_name":"byrongomezjr/kubernetes-api","owner":"byrongomezjr","description":"A Go-based Kubernetes API service demonstrating DevOps practices including Docker containerization, CI/CD with GitHub Actions, and Kubernetes deployment.","archived":false,"fork":false,"pushed_at":"2025-02-04T00:56:38.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-04T01:27:00.666Z","etag":null,"topics":["api","ci-cd","containerization","devops","docker","github-actions","golang","kubernetes","kubernetes-deployment"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/byrongomezjr.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-03T23:15:13.000Z","updated_at":"2025-02-04T00:56:41.000Z","dependencies_parsed_at":"2025-02-04T01:27:02.262Z","dependency_job_id":"0e657864-3056-4652-b043-bca6b3a1fe38","html_url":"https://github.com/byrongomezjr/kubernetes-api","commit_stats":null,"previous_names":["byrongomezjr/kubernetes-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byrongomezjr%2Fkubernetes-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byrongomezjr%2Fkubernetes-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byrongomezjr%2Fkubernetes-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byrongomezjr%2Fkubernetes-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/byrongomezjr","download_url":"https://codeload.github.com/byrongomezjr/kubernetes-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246194274,"owners_count":20738645,"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","ci-cd","containerization","devops","docker","github-actions","golang","kubernetes","kubernetes-deployment"],"created_at":"2025-02-04T15:25:48.448Z","updated_at":"2025-12-30T23:18:30.612Z","avatar_url":"https://github.com/byrongomezjr.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kubernetes API\n\nA production-grade Golang API service designed to demonstrate enterprise-level Kubernetes deployment practices.\n\n## Features\n\n- **Robust Go API**: RESTful API with proper error handling, middleware, and versioning\n- **Authentication**: JWT-based authentication system with secure password hashing\n- **Database Integration**: PostgreSQL integration with connection pooling and migrations\n- **Metrics and Monitoring**: Prometheus metrics endpoint for observability\n- **Advanced Kubernetes Deployment**:\n  - Resource limits and requests\n  - Horizontal Pod Autoscaling\n  - Liveness and readiness probes\n  - ConfigMaps and Secrets management\n  - Network Policies for security\n  - Ingress with TLS\n  - Pod Disruption Budget for high availability\n- **Helm Chart**: Complete Helm chart for easy deployment\n- **CI/CD Pipeline**: GitHub Actions workflow for testing, building, and deploying\n\n## Prerequisites\n\n- Go (1.22 or later)\n- Docker and Docker Compose\n- Kubernetes cluster (for deployment)\n- Helm (v3.x)\n- kubectl\n\n## Architecture\n\nThis application follows a clean, layered architecture:\n\n- `internal/api` - API handlers and routing\n- `internal/models` - Data models and DTOs\n- `internal/database` - Database connections and data access\n- `internal/auth` - Authentication system\n- `internal/metrics` - Prometheus metrics\n- `pkg/utils` - Common utilities\n- `k8s/` - Kubernetes manifests\n- `helm/` - Helm chart for Kubernetes deployment\n\n## Local Development\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/byrongomezjr/kubernetes-api.git\n   cd kubernetes-api\n   ```\n\n2. Set up environment:\n   ```bash\n   cp configs/env.sample .env\n   # Edit .env with your configuration\n   ```\n\n3. Start dependencies with Docker Compose:\n   ```bash\n   docker-compose up -d postgres\n   ```\n\n4. Build and run the application:\n   ```bash\n   go build -v ./...\n   ./kubernetes-api\n   ```\n\n5. Run tests:\n   ```bash\n   go test -v ./...\n   ```\n\n## API Endpoints\n\n### Public Endpoints\n\n- `GET /api/health` - Health check endpoint\n- `POST /api/v1/auth/register` - Register a new user\n- `POST /api/v1/auth/login` - Authenticate a user\n\n### Protected Endpoints (Require JWT)\n\n- `GET /api/v1/items` - Get all items\n- `POST /api/v1/items` - Create a new item\n- `GET /api/v1/items/{id}` - Get an item by ID\n- `PUT /api/v1/items/{id}` - Update an item\n- `DELETE /api/v1/items/{id}` - Delete an item\n\n## Kubernetes Deployment\n\n### Using kubectl\n\n1. Build and push the Docker image:\n   ```bash\n   docker build -t byrongomezjr/kubernetes-api:latest .\n   docker push byrongomezjr/kubernetes-api:latest\n   ```\n\n2. Create namespace and deploy:\n   ```bash\n   kubectl apply -f k8s/namespace.yaml\n   kubectl apply -f k8s/secret.yaml\n   kubectl apply -f k8s/configmap.yaml\n   kubectl apply -f k8s/postgres.yaml\n   kubectl apply -f k8s/deployment.yaml\n   kubectl apply -f k8s/service.yaml\n   kubectl apply -f k8s/ingress.yaml\n   kubectl apply -f k8s/hpa.yaml\n   kubectl apply -f k8s/pdb.yaml\n   kubectl apply -f k8s/networkpolicy.yaml\n   ```\n\n### Using Helm\n\n1. Install or upgrade using Helm:\n   ```bash\n   helm upgrade --install kubernetes-api ./helm/kubernetes-api \\\n     --namespace kubernetes-api --create-namespace \\\n     --set image.tag=latest \\\n     --set secrets.JWT_SECRET=\"your-secure-secret-key\"\n   ```\n\n2. Verify the deployment:\n   ```bash\n   kubectl get pods -n kubernetes-api\n   ```\n\n## CI/CD Pipeline\n\nThe project uses GitHub Actions for CI/CD. The workflow (`/.github/workflows/ci-cd.yml`) includes:\n\n1. **Build and Test**:\n   - Build the application\n   - Run unit tests\n   - Run linting\n\n2. **Docker Build and Push**:\n   - Build the Docker image\n   - Push to Docker Hub with appropriate tags\n\n3. **Kubernetes Deployment**:\n   - Deploy to Kubernetes using Helm\n   - Verify the deployment\n\nTo set up the pipeline, you need to configure the following secrets in your GitHub repository:\n- `DOCKERHUB_USERNAME` - Docker Hub username\n- `DOCKERHUB_TOKEN` - Docker Hub token/password\n- `KUBE_CONFIG` - Kubernetes configuration file (base64 encoded)\n- `JWT_SECRET` - Secret key for JWT\n\n### Setting up Kubernetes Deployment in CI/CD\n\nFor the deployment step to work correctly, you need to configure a valid Kubernetes configuration:\n\n1. **Generate a kubeconfig file** with access to your cluster:\n   ```bash\n   kubectl config view --minify --flatten \u003e kubeconfig.yaml\n   ```\n\n2. **Encode the file to base64**:\n   ```bash\n   # Linux/macOS\n   cat kubeconfig.yaml | base64 -w 0\n   \n   # Windows (PowerShell)\n   [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes((Get-Content -Raw kubeconfig.yaml)))\n   ```\n\n3. **Add as a GitHub Secret**:\n   - Go to your repository on GitHub\n   - Navigate to Settings \u003e Secrets and variables \u003e Actions\n   - Click \"New repository secret\"\n   - Name: `KUBE_CONFIG`\n   - Value: Paste the base64 encoded string\n   \n4. **Grant necessary permissions**:\n   - Ensure the service account in your kubeconfig has permissions to deploy to the target namespace\n\n**Note**: If you don't have a Kubernetes cluster yet, the deployment step will be skipped automatically.\n\n## Monitoring\n\nThe application exposes metrics at the `/metrics` endpoint in Prometheus format. You can configure Prometheus to scrape these metrics and visualize them using Grafana.\n\n## Security Features\n\n- Non-root user in Docker container\n- Read-only root filesystem\n- Resource limits\n- Network policies\n- Secure secrets management\n- JWT authentication\n\n## Contributing\n\n1. Fork the repository\n2. Create a new branch for your changes\n3. Make your changes and commit them\n4. Push your changes to your fork\n5. Create a pull request\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Contact\n\nFor questions or feedback, please contact me at byrongomezjr@protonmail.com\n\n## Security Notes\n\n### Environment Variables\nThis application uses environment variables for configuration. Never commit actual secrets to the repository.\n\n1. Copy `.env.template` to `.env` and fill in your values:\n   ```bash\n   cp .env.template .env\n   # Edit .env with your actual values\n   ```\n\n2. For Kubernetes deployments, use sealed secrets or a secret management solution:\n   ```bash\n   # Create your secret from the template\n   cp k8s/secret.template.yaml k8s/secret.yaml\n   # Edit secret.yaml with your base64 encoded values\n   ```\n\n### Kubernetes Secrets\nThe `k8s/secret.yaml` file is excluded from git. You need to create this file manually based on the template.\n\n## Environment Variables\n\nThis application uses the following environment variables for configuration:\n\n### Database Configuration\n- `DB_HOST`: PostgreSQL database host (default: `localhost`)\n- `DB_PORT`: PostgreSQL database port (default: `5432`)\n- `DB_USER`: PostgreSQL database username (default: `postgres`)\n- `DB_PASSWORD`: PostgreSQL database password (required)\n- `DB_NAME`: PostgreSQL database name (required)\n- `DB_SSLMODE`: PostgreSQL SSL mode (default: `disable`, options: `disable`, `require`, `verify-ca`, `verify-full`)\n\n### JWT Configuration\n- `JWT_SECRET`: Secret key for JWT token signing (required)\n\n### API Configuration\n- `API_PORT`: Port the API server listens on (default: `8080`)\n- `API_HOST`: Host the API server binds to (default: `0.0.0.0`)\n- `LOG_LEVEL`: Logging level (default: `info`, options: `debug`, `info`, `warn`, `error`)\n\n### Environment\n- `ENV`: Application environment (default: `development`, options: `development`, `testing`, `production`)\n\n### Setting Environment Variables\n\n#### Local Development\nFor local development, copy the example file and set your values:\n```bash\ncp .env.example .env\n# Edit .env with appropriate values\n```\n\n#### Docker Compose\nWhen using Docker Compose, environment variables can be set in the `docker-compose.yml` file:\n```yaml\nservices:\n  api:\n    environment:\n      - DB_HOST=postgres\n      - DB_PORT=5432\n      - DB_USER=postgres\n      - DB_PASSWORD=mysecretpassword\n      # ... other variables\n```\n\n#### Kubernetes\nFor Kubernetes deployments, sensitive variables should be stored in Secrets:\n```yaml\napiVersion: v1\nkind: Secret\nmetadata:\n  name: kubernetes-api-secrets\n  namespace: kubernetes-api\ntype: Opaque\ndata:\n  DB_PASSWORD: base64_encoded_password\n  JWT_SECRET: base64_encoded_jwt_secret\n```\n\nNon-sensitive configuration can be stored in ConfigMaps:\n```yaml\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: kubernetes-api-config\n  namespace: kubernetes-api\ndata:\n  DB_HOST: postgres.kubernetes-api.svc.cluster.local\n  DB_PORT: \"5432\"\n  DB_USER: api_user\n  DB_NAME: api_database\n  API_PORT: \"8080\"\n  LOG_LEVEL: \"info\"\n  ENV: \"production\"\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyrongomezjr%2Fkubernetes-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbyrongomezjr%2Fkubernetes-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyrongomezjr%2Fkubernetes-api/lists"}