first commit
This commit is contained in:
d.viti
432
web/docs/getting-started.md
Normal file
432
web/docs/getting-started.md
Normal file
@@ -0,0 +1,432 @@
|
||||
# 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!*
|
||||
Reference in New Issue
Block a user