433 lines
8.5 KiB
Markdown
433 lines
8.5 KiB
Markdown
# Getting Started
|
||
|
||
Quick start guide for working with the API Gateway infrastructure and applications.
|
||
|
||
## Prerequisites
|
||
|
||
- Access to Kubernetes cluster with `kubectl` configured
|
||
- Access to Gateway Dashboard
|
||
- CLI tools installed (optional, for command-line configuration)
|
||
- Git repository access for application code
|
||
|
||
## Quick Start - Local Development
|
||
|
||
### 1. Clone Repository
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd <project-directory>
|
||
```
|
||
|
||
### 2. Run Applications Locally
|
||
|
||
**Web Application**:
|
||
```bash
|
||
cd web
|
||
pip install -r requirements.txt
|
||
python main.py
|
||
# Access at http://localhost:8000
|
||
```
|
||
|
||
**API Application**:
|
||
```bash
|
||
cd api
|
||
pip install -r requirements.txt
|
||
python main.py
|
||
# Swagger UI at http://localhost:8000/docs
|
||
```
|
||
|
||
### 3. Build Docker Images
|
||
|
||
```bash
|
||
# Web application
|
||
docker build -t web-app ./web
|
||
|
||
# API application
|
||
docker build -t api-app ./api
|
||
```
|
||
|
||
## Deploying to Kubernetes
|
||
|
||
### 1. Prepare Namespace
|
||
|
||
```bash
|
||
# Create namespace if it doesn't exist
|
||
kubectl create namespace <namespace>
|
||
|
||
# Verify gateway components are running
|
||
kubectl get pods -n <namespace>
|
||
```
|
||
|
||
**Expected Components**:
|
||
- ✅ Dashboard pod running
|
||
- ✅ Developer Portal pod running
|
||
- ✅ Data Plane Manager pod running
|
||
- ✅ Gateway pods running (multiple replicas)
|
||
- ✅ Database pod running
|
||
|
||
### 2. Create Kubernetes Manifests
|
||
|
||
**deployment.yaml**:
|
||
```yaml
|
||
apiVersion: apps/v1
|
||
kind: Deployment
|
||
metadata:
|
||
name: web
|
||
namespace: <namespace>
|
||
spec:
|
||
replicas: 2
|
||
selector:
|
||
matchLabels:
|
||
app: web
|
||
template:
|
||
metadata:
|
||
labels:
|
||
app: web
|
||
spec:
|
||
containers:
|
||
- name: web
|
||
image: <registry>/web:latest
|
||
ports:
|
||
- containerPort: 8000
|
||
name: http
|
||
livenessProbe:
|
||
httpGet:
|
||
path: /health
|
||
port: 8000
|
||
readinessProbe:
|
||
httpGet:
|
||
path: /health
|
||
port: 8000
|
||
---
|
||
apiVersion: v1
|
||
kind: Service
|
||
metadata:
|
||
name: web-service
|
||
namespace: <namespace>
|
||
spec:
|
||
type: ClusterIP
|
||
ports:
|
||
- port: 80
|
||
targetPort: 8000
|
||
name: http
|
||
selector:
|
||
app: web
|
||
```
|
||
|
||
### 3. Deploy Applications
|
||
|
||
```bash
|
||
kubectl apply -f deployment.yaml
|
||
|
||
# Check deployment status
|
||
kubectl get deployments -n <namespace>
|
||
kubectl get pods -n <namespace> -l app=web
|
||
```
|
||
|
||
### 4. Configure Container Registry Access (if needed)
|
||
|
||
```bash
|
||
# Create registry secret
|
||
kubectl create secret docker-registry registry-secret \
|
||
--docker-server=<registry-server> \
|
||
--docker-username=<USERNAME> \
|
||
--docker-password=<TOKEN> \
|
||
-n <namespace>
|
||
|
||
# Add to deployment
|
||
spec:
|
||
template:
|
||
spec:
|
||
imagePullSecrets:
|
||
- name: registry-secret
|
||
```
|
||
|
||
## Configuring Gateway Routes
|
||
|
||
### Method 1: Using CLI Tools
|
||
|
||
**1. Create configuration file** (`config.yaml`):
|
||
|
||
```yaml
|
||
services:
|
||
- name: web-service
|
||
upstream:
|
||
name: web-upstream
|
||
scheme: http
|
||
type: roundrobin
|
||
discovery_type: kubernetes
|
||
service_name: <namespace>/web-service:http
|
||
routes:
|
||
- name: web-route
|
||
uris:
|
||
- /*
|
||
hosts:
|
||
- app.domain.com
|
||
plugins:
|
||
redirect:
|
||
http_to_https: true
|
||
```
|
||
|
||
**2. Sync configuration**:
|
||
|
||
```bash
|
||
<cli-tool> sync -f config.yaml \
|
||
--server <dashboard-url> \
|
||
--token <api-token> \
|
||
--gateway-group default
|
||
```
|
||
|
||
**3. Verify sync**:
|
||
```bash
|
||
# Expected output:
|
||
[CLI] › ✔ success Create service: "web-service"
|
||
[CLI] › ✔ success Create route: "web-route"
|
||
```
|
||
|
||
### Method 2: Using Dashboard Web UI
|
||
|
||
**1. Access Dashboard**:
|
||
- URL: Gateway Dashboard URL
|
||
- Login with credentials
|
||
|
||
**2. Configure Service Discovery** (one-time setup):
|
||
- Navigate: **Settings → Service Registry**
|
||
- Click: **Add Service Registry**
|
||
- Select: **Kubernetes**
|
||
- Configure:
|
||
```
|
||
Name: kubernetes-cluster
|
||
API Server: https://kubernetes.default.svc.cluster.local:443
|
||
Token Path: /var/run/secrets/kubernetes.io/serviceaccount/token
|
||
Namespace Filter: <namespace>
|
||
```
|
||
- Save and verify status shows "Connected"
|
||
|
||
**3. Create Service**:
|
||
- Navigate: **Services**
|
||
- Click: **Create Service**
|
||
- Name: `web-service`
|
||
- Upstream Type: **Service Discovery**
|
||
- Discovery Type: **Kubernetes**
|
||
- Service Name: `<namespace>/web-service:http`
|
||
|
||
**4. Create Route**:
|
||
- In the service page, go to **Routes** tab
|
||
- Click: **Create Route**
|
||
- Name: `web-route`
|
||
- Host: `app.domain.com`
|
||
- Path: `/*`
|
||
- Methods: GET, POST, PUT, DELETE
|
||
- Add Plugin: **redirect** → `http_to_https: true`
|
||
|
||
**5. Publish Route**:
|
||
- Find route in the Routes tab
|
||
- Click: **Publish**
|
||
- Select gateway group: **default**
|
||
- Confirm
|
||
|
||
## Creating Ingress for External Access
|
||
|
||
**ingress.yaml**:
|
||
```yaml
|
||
apiVersion: networking.k8s.io/v1
|
||
kind: Ingress
|
||
metadata:
|
||
name: app-ingress
|
||
namespace: <namespace>
|
||
spec:
|
||
ingressClassName: nginx
|
||
tls:
|
||
- hosts:
|
||
- app.domain.com
|
||
secretName: app-tls
|
||
rules:
|
||
- host: app.domain.com
|
||
http:
|
||
paths:
|
||
- path: /
|
||
pathType: Prefix
|
||
backend:
|
||
service:
|
||
name: gateway-service
|
||
port:
|
||
number: 80
|
||
```
|
||
|
||
**Important**: Backend points to Gateway service, not application service directly.
|
||
|
||
```bash
|
||
kubectl apply -f ingress.yaml
|
||
```
|
||
|
||
## Verifying Service Discovery RBAC
|
||
|
||
Gateway needs permissions to discover Kubernetes services:
|
||
|
||
```bash
|
||
# Check current permissions
|
||
kubectl auth can-i list endpoints --as=system:serviceaccount:<namespace>:default -n <namespace>
|
||
|
||
# If needed, create ClusterRoleBinding
|
||
kubectl create clusterrolebinding gateway-discovery \
|
||
--clusterrole=view \
|
||
--serviceaccount=<namespace>:default
|
||
```
|
||
|
||
## Testing the Deployment
|
||
|
||
### 1. Test DNS Resolution
|
||
|
||
```bash
|
||
# Add to /etc/hosts or configure DNS
|
||
echo "<external-ip> app.domain.com" | sudo tee -a /etc/hosts
|
||
```
|
||
|
||
### 2. Test HTTP to HTTPS Redirect
|
||
|
||
```bash
|
||
curl -I http://app.domain.com
|
||
|
||
# Expected:
|
||
# HTTP/1.1 301 Moved Permanently
|
||
# Location: https://app.domain.com
|
||
```
|
||
|
||
### 3. Test Application Access
|
||
|
||
```bash
|
||
# Web application
|
||
curl https://app.domain.com
|
||
|
||
# API health check
|
||
curl https://app.domain.com/api/health
|
||
```
|
||
|
||
### 4. Verify Service Discovery
|
||
|
||
```bash
|
||
# Scale deployment
|
||
kubectl scale deployment web -n <namespace> --replicas=5
|
||
|
||
# Check endpoints
|
||
kubectl get endpoints -n <namespace> web-service
|
||
|
||
# Gateway automatically discovers all 5 pod endpoints
|
||
# No configuration change needed
|
||
```
|
||
|
||
## Accessing Gateway Dashboard
|
||
|
||
### Local Access (port-forward)
|
||
|
||
```bash
|
||
kubectl port-forward -n <namespace> svc/dashboard-service 7080:7080
|
||
|
||
# Access at http://localhost:7080
|
||
```
|
||
|
||
### Public Access
|
||
|
||
Direct access via configured URLs:
|
||
- **Dashboard**: Management interface URL
|
||
- **Developer Portal**: Developer portal URL
|
||
|
||
## CI/CD Pipeline Setup
|
||
|
||
### 1. Configure Repository Token
|
||
|
||
In repository settings:
|
||
1. Go to **Settings → Secrets**
|
||
2. Add authentication token
|
||
3. Configure with appropriate permissions
|
||
4. Enable container registry access
|
||
|
||
### 2. Push to Trigger Build
|
||
|
||
```bash
|
||
git add .
|
||
git commit -m "Deploy applications"
|
||
git push origin main
|
||
```
|
||
|
||
The pipeline will:
|
||
- Build Docker images
|
||
- Push to container registry
|
||
- Tag with branch/version
|
||
|
||
### 3. Update Kubernetes Deployment
|
||
|
||
```bash
|
||
# Manually trigger rollout
|
||
kubectl rollout restart deployment/web -n <namespace>
|
||
kubectl rollout restart deployment/api -n <namespace>
|
||
|
||
# Or update image in deployment
|
||
kubectl set image deployment/web web=<registry>/web:latest -n <namespace>
|
||
```
|
||
|
||
## Common Tasks
|
||
|
||
### View Logs
|
||
|
||
```bash
|
||
# Application logs
|
||
kubectl logs -n <namespace> -l app=web --tail=50 -f
|
||
|
||
# Gateway logs
|
||
kubectl logs -n <namespace> -l app.kubernetes.io/name=gateway --tail=50 -f
|
||
|
||
# Dashboard logs
|
||
kubectl logs -n <namespace> -l app=dashboard --tail=50 -f
|
||
```
|
||
|
||
### Check Route Configuration
|
||
|
||
**Via CLI**:
|
||
```bash
|
||
<cli-tool> dump \
|
||
--server <dashboard-url> \
|
||
--token <TOKEN>
|
||
```
|
||
|
||
**Via Dashboard**:
|
||
- Navigate: **Services → <service-name> → Routes**
|
||
- View route details and publication status
|
||
|
||
### Update Route Configuration
|
||
|
||
```bash
|
||
# Edit config file
|
||
vim config.yaml
|
||
|
||
# Sync changes
|
||
<cli-tool> sync -f config.yaml \
|
||
--server <dashboard-url> \
|
||
--token <TOKEN> \
|
||
--gateway-group default
|
||
```
|
||
|
||
### Monitor Gateway Metrics
|
||
|
||
**Prometheus**:
|
||
```bash
|
||
kubectl port-forward -n <namespace> svc/prometheus-server 9090:9090
|
||
|
||
# Access at http://localhost:9090
|
||
```
|
||
|
||
**Dashboard Metrics**:
|
||
- Navigate: **Monitoring** in Gateway Dashboard
|
||
- View request rates, latency, error rates
|
||
|
||
## Next Steps
|
||
|
||
- [Configure advanced routing](api7-configuration.md)
|
||
- [Set up monitoring and alerts](monitoring.md)
|
||
- [Review troubleshooting guide](troubleshooting.md)
|
||
- [Learn about the architecture](architecture.md)
|
||
|
||
---
|
||
|
||
*You're now ready to deploy and manage applications with the API Gateway infrastructure!*
|