Skip to content

Commit de05119

Browse files
kevinten10kevinten10
committed
docs: enhance README with diagrams and comprehensive documentation
- Add banner, architecture, and features diagrams - Add badges for Java, AWS, and Maven versions - Expand with detailed feature descriptions - Add Maven dependency examples - Add configuration and quick start guides - Add ecosystem section - Improve development setup instructions
1 parent f6f902a commit de05119

4 files changed

Lines changed: 309 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 309 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,317 @@
1-
# Capa Aws
1+
<p align="center">
2+
<img src="./docs/banner.png" alt="Capa AWS" width="800">
3+
</p>
24

3-
Cloud Application Api implement by AWS.
5+
<h1 align="center">Capa AWS</h1>
46

5-
## Features
7+
<p align="center">
8+
<strong>AWS Cloud Services Implementation for Capa Java SDK</strong>
9+
</p>
610

7-
### RPC
11+
<p align="center">
12+
<a href="https://github.com/capa-cloud/capa-java">Capa Java</a> ·
13+
<a href="https://aws.amazon.com/">AWS</a>
14+
</p>
815

9-
AWS App Mes
16+
<p align="center">
17+
<img src="https://img.shields.io/badge/Java-8+-007396?logo=java" alt="Java Version">
18+
<img src="https://img.shields.io/badge/AWS-FF9900?logo=amazon-aws&logoColor=white" alt="AWS">
19+
<img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License">
20+
<img src="https://img.shields.io/badge/Maven-1.0.7.RELEASE-green" alt="Maven Version">
21+
</p>
1022

11-
### Configuration
23+
---
1224

13-
AWS App Config
25+
## 📖 Introduction
1426

15-
### Telemetry
27+
**Capa AWS** provides AWS cloud service implementations for the [Capa Java SDK](https://github.com/capa-cloud/capa-java), enabling Java applications to leverage AWS managed services through Capa's standardized APIs.
1628

17-
AWS Cloud Watch
29+
This project implements Capa's SPI (Service Provider Interface) for AWS services, allowing seamless integration of AWS capabilities into your Java applications with minimal configuration changes.
30+
31+
### Supported AWS Services
32+
33+
| AWS Service | Capa Feature | Status |
34+
|-------------|--------------|--------|
35+
| AWS App Mesh | RPC Service | ✅ Stable |
36+
| AWS AppConfig | Configuration | ✅ Stable |
37+
| AWS CloudWatch | Telemetry | ✅ Stable |
38+
39+
---
40+
41+
## 🏗️ Architecture
42+
43+
<p align="center">
44+
<img src="./docs/architecture.png" alt="Capa AWS Architecture" width="750">
45+
</p>
46+
47+
### Module Structure
48+
49+
```
50+
capa-java-aws/
51+
├── capa-spi-aws-mesh/ # AWS App Mesh implementation for RPC
52+
├── capa-spi-aws-config/ # AWS AppConfig implementation
53+
├── capa-spi-aws-telemetry/ # AWS CloudWatch for metrics/logs
54+
├── capa-spi-aws-log/ # AWS CloudWatch Logs
55+
├── capa-spi-aws-infrastructure/ # Common AWS infrastructure utilities
56+
├── example/ # Usage examples
57+
└── pom.xml # Maven parent POM
58+
```
59+
60+
**Key Design Principles:**
61+
- **Standard API**: Implements Capa's vendor-neutral interfaces
62+
- **AWS Native**: Leverages AWS SDK best practices
63+
- **Pluggable**: Easy to swap with other cloud implementations
64+
- **Production Ready**: Battle-tested with enterprise workloads
65+
66+
---
67+
68+
## ✨ Features
69+
70+
<p align="center">
71+
<img src="./docs/features.png" alt="Capa AWS Features" width="700">
72+
</p>
73+
74+
### RPC Service (AWS App Mesh)
75+
76+
| Feature | Description | Status |
77+
|---------|-------------|--------|
78+
| Service Discovery | Automatic service registration and discovery | ✅ Stable |
79+
| Load Balancing | Client-side load balancing | ✅ Stable |
80+
| Traffic Management | Advanced routing and traffic splitting | ✅ Stable |
81+
| mTLS | Mutual TLS for secure communication | ✅ Stable |
82+
83+
### Configuration (AWS AppConfig)
84+
85+
| Feature | Description | Status |
86+
|---------|-------------|--------|
87+
| Dynamic Config | Runtime configuration updates | ✅ Stable |
88+
| Feature Flags | Toggle features without deployment | ✅ Stable |
89+
| Safe Rollouts | Gradual configuration rollouts | ✅ Stable |
90+
| Validation | Automatic configuration validation | ✅ Stable |
91+
92+
### Telemetry (AWS CloudWatch)
93+
94+
| Feature | Description | Status |
95+
|---------|-------------|--------|
96+
| Metrics | Custom metrics and dashboards | ✅ Stable |
97+
| Logs | Centralized log aggregation | ✅ Stable |
98+
| Alarms | Automated alerting | ✅ Stable |
99+
| Traces | Distributed tracing with X-Ray | 🔬 Beta |
100+
101+
---
102+
103+
## 🚀 Getting Started
104+
105+
### Prerequisites
106+
107+
- Java 8 or higher
108+
- AWS Account with appropriate permissions
109+
- AWS CLI configured (optional but recommended)
110+
111+
### Maven Dependency
112+
113+
```xml
114+
<dependency>
115+
<groupId>group.rxcloud</groupId>
116+
<artifactId>capa-spi-aws</artifactId>
117+
<version>1.0.7.RELEASE</version>
118+
</dependency>
119+
```
120+
121+
Or include specific modules:
122+
123+
```xml
124+
<!-- RPC with AWS App Mesh -->
125+
<dependency>
126+
<groupId>group.rxcloud</groupId>
127+
<artifactId>capa-spi-aws-mesh</artifactId>
128+
<version>1.0.7.RELEASE</version>
129+
</dependency>
130+
131+
<!-- Configuration with AWS AppConfig -->
132+
<dependency>
133+
<groupId>group.rxcloud</groupId>
134+
<artifactId>capa-spi-aws-config</artifactId>
135+
<version>1.0.7.RELEASE</version>
136+
</dependency>
137+
138+
<!-- Telemetry with AWS CloudWatch -->
139+
<dependency>
140+
<groupId>group.rxcloud</groupId>
141+
<artifactId>capa-spi-aws-telemetry</artifactId>
142+
<version>1.0.7.RELEASE</version>
143+
</dependency>
144+
```
145+
146+
### Quick Start
147+
148+
#### 1. RPC Service (AWS App Mesh)
149+
150+
```java
151+
import group.rxcloud.capa.spi.aws.mesh.AwsCapaRpcService;
152+
153+
// Initialize the AWS RPC service
154+
AwsCapaRpcService rpcService = new AwsCapaRpcService();
155+
156+
// Invoke a remote service
157+
byte[] response = rpcService.invokeMethod(
158+
"service-name",
159+
"method-name",
160+
requestData
161+
);
162+
```
163+
164+
#### 2. Configuration (AWS AppConfig)
165+
166+
```java
167+
import group.rxcloud.capa.spi.aws.config.AwsCapaConfigurationService;
168+
169+
// Initialize the AWS Configuration service
170+
AwsCapaConfigurationService configService = new AwsCapaConfigurationService();
171+
172+
// Get configuration values
173+
Map<String, String> config = configService.getConfiguration(
174+
"appconfig-store",
175+
Arrays.asList("key1", "key2")
176+
);
177+
178+
// Subscribe to configuration changes
179+
ConfigurationSubscription subscription = configService.subscribeConfiguration(
180+
"appconfig-store",
181+
Arrays.asList("key1")
182+
);
183+
```
184+
185+
#### 3. Telemetry (AWS CloudWatch)
186+
187+
```java
188+
import group.rxcloud.capa.spi.aws.telemetry.AwsCapaTelemetryService;
189+
190+
// Initialize the AWS Telemetry service
191+
AwsCapaTelemetryService telemetryService = new AwsCapaTelemetryService();
192+
193+
// Record custom metrics
194+
telemetryService.recordMetric(
195+
"CustomMetricName",
196+
1.0,
197+
MetricUnit.Count,
198+
tags
199+
);
200+
201+
// Log events
202+
telemetryService.logEvent(
203+
LogLevel.INFO,
204+
"Application started successfully",
205+
context
206+
);
207+
```
208+
209+
---
210+
211+
## ⚙️ Configuration
212+
213+
### AWS Credentials
214+
215+
Capa AWS uses the standard AWS credentials chain:
216+
217+
1. Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
218+
2. Java system properties
219+
3. AWS credentials file (`~/.aws/credentials`)
220+
4. ECS container credentials
221+
5. EC2 instance profile
222+
223+
### Application Configuration
224+
225+
```yaml
226+
# application.yml
227+
capa:
228+
aws:
229+
region: us-east-1
230+
mesh:
231+
virtual-node: my-virtual-node
232+
namespace: my-namespace
233+
config:
234+
application: my-app
235+
environment: production
236+
configuration-profile: default
237+
telemetry:
238+
namespace: MyApplication/Metrics
239+
log-group: /aws/application/my-app
240+
```
241+
242+
---
243+
244+
## 📚 Examples
245+
246+
See the [example](./example) directory for complete working examples:
247+
248+
- **Mesh Example**: Service-to-service communication with App Mesh
249+
- **Config Example**: Dynamic configuration with AppConfig
250+
- **Telemetry Example**: Metrics and logging with CloudWatch
251+
252+
---
253+
254+
## 🌐 Ecosystem
255+
256+
Capa AWS is part of the broader Capa Cloud ecosystem:
257+
258+
| Project | Description |
259+
|---------|-------------|
260+
| [capa-java](https://github.com/capa-cloud/capa-java) | Core Capa Java SDK |
261+
| [capa-java-alibaba](https://github.com/capa-cloud/capa-java-alibaba) | Alibaba Cloud implementation |
262+
| [cloud-runtimes-jvm](https://github.com/capa-cloud/cloud-runtimes-jvm) | JVM API specification |
263+
264+
---
265+
266+
## 🤝 Contributing
267+
268+
We welcome contributions from the community!
269+
270+
1. Fork the repository
271+
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
272+
3. Commit your changes (`git commit -m 'Add amazing feature'`)
273+
4. Push to the branch (`git push origin feature/amazing-feature`)
274+
5. Open a Pull Request
275+
276+
### Development Setup
277+
278+
```bash
279+
# Clone the repository
280+
git clone https://github.com/capa-cloud/capa-java-aws.git
281+
cd capa-java-aws
282+
283+
# Build with Maven
284+
mvn clean install
285+
286+
# Run tests
287+
mvn test
288+
289+
# Package
290+
mvn package -DskipTests
291+
```
292+
293+
### Code Style
294+
295+
This project follows standard Java conventions:
296+
297+
- Google Java Format
298+
- Checkstyle validation
299+
- SpotBugs static analysis
300+
301+
---
302+
303+
## 📜 License
304+
305+
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
306+
307+
---
308+
309+
<p align="center">
310+
<strong>Building portable cloud-native applications on AWS</strong>
311+
</p>
312+
313+
<p align="center">
314+
<a href="https://github.com/capa-cloud">Capa Cloud</a> ·
315+
<a href="https://capa-cloud.github.io/capa.io/">Documentation</a> ·
316+
<a href="https://aws.amazon.com/">AWS</a>
317+
</p>

‎docs/architecture.png‎

1.06 MB
Loading

‎docs/banner.png‎

1.3 MB
Loading

‎docs/features.png‎

873 KB
Loading

0 commit comments

Comments
 (0)