Explore, Dream, Discover

redis - sharding

Sun, 07 Jul 2024 00:00:00 +0000

TL; DR

Sharding은 수평분할과 관련된 아키텍쳐 패턴입니다. 수평 확장과 단일 장애점(SPOF) 문제를 개선하기에 용이하지만, 그만큼 올바르게 동작하도록 구성하려면 많은 비용과 노력이 필요합니다.

What is Sharding?

각 파티션이 동일한 스키마와 열을 갖지만 그 데이터인 행은 다르게 나누어 갖습니다. 위 그림이 이 내용을 쉽게 설명하고 있는데, Sharding은 Horizontal Partitions 방식으로 데이터를 나누어 저장하는 것을 의미합니다.

Pros & Cons

Pros

Scale out에 용이합니다.
큰 테이블을 여러개로 샤딩하면 쿼리 성능이 올라갈 수 있습니다.
특정 Sharding된 영역에 문제 생긴다고 해도, 전체 서비스 장애가 발생하는 것을 막을 수 있습니다.
Cons
Sharding을 제대로 구현하고 적용하는데 어려움이 많습니다. 잘못 구성하게 되면 데이터 손실등이 발생할 수 있습니다.
샤딩 알고리즘 등에 따라 샤드가 불균해질 수 있고 이를 관리해줘야 할 수 있습니다.
샤딩된 구조를 단일 아키텍쳐로 돌리기 어렵습니다.

Sharding Strategies

키 기반 샤딩(Key-based Sharding)

• 설명: 각 데이터 항목에 대해 특정 키(예: 해시 함수 결과)를 사용하여 샤드를 결정합니다. • 특징: 해시 함수에 의해 고르게 분포되도록 설계되어 있어, 모든 샤드에 걸쳐 데이터가 균등하게 분포됩니다.

범위 기반 샤딩(Range-based Sharding)

• 설명: 특정 범위의 값을 기반으로 데이터를 샤드에 분할합니다. • 특징: 연속적인 데이터 범위가 같은 샤드에 저장되므로, 특정 범위의 데이터를 조회할 때 효율적입니다.

디렉토리 기반 샤딩(Directory-based Sharding)

• 설명: 샤딩 디렉토리라는 매핑 테이블을 사용하여 데이터 항목이 어떤 샤드에 있는지 관리합니다. • 특징: 유연하지만 디렉토리 테이블을 관리하기 위한 오버헤드가 발생할 수 있습니다.

References

https://www.digitalocean.com/community/tutorials/understanding-database-sharding

redis - hashtag

Sun, 07 Jul 2024 00:00:00 +0000

TL;DR

redis cluster mode에서 MGET으로 데이터를 가져오려면, 저장할때 key에 hashtag인 {}를 포함해주어야 합니다.
Hashslot

CROSSSLOT Keys in request don’t hash to the same slot

위와 같은 에러 메세지를 받았다면, cluster mode로 실행중인 redis에 MGET등으로 한번에 많은 요청을 받으려고 시도 할 때 발생합니다. aws 질문글 중에 관련된 내용이 있는데, 문제를 해결하기 위해서 키 내에 hashslot 명시하는 기준인 hashtag {} 를 포함하면 됩니다. 하지만, 기본적으로 cluster mode에서 hashslot이 저장되는 방식에 대한 이해를 바탕으로 hashslot을 설정하는 것이 좋습니다.

아래와 같은 key를 예시로 들어봅니다.

1. categories:movies:{1}:name
2. categories:{movies}:1:name

cluster mode의 경우 hashslot을 n개의 shard로 나누어 관리하므로 같은 공간에 저장되는 것이 좋습니다. 담고자 하는 정보가 동일한 hashslot에 묶여 함께 저장되길 바라는 곳에 {}를 포함해야 합니다.

따라서, 특정 영화의 여러 속성을 한 번에 가져오는 경우가 더 일반적이라면 첫 번째 구조를 추천합니다. 그러나 범주 내의 여러 영화를 한 번에 가져오는 경우가 더 일반적이라면 두 번째 구조를 사용할 수 있습니다.

Refrences

https://redis.io/docs/latest/develop/use/keyspace/
https://repost.aws/knowledge-center/elasticache-crossslot-keys-error-redis
https://redis.io/docs/latest/operate/oss_and_stack/reference/cluster-spec/

go-redis - go-redis v9 에서 hash 타입을 다루는 방법

Sun, 07 Jul 2024 00:00:00 +0000

TL;DR

go-reds v9 버전부터
- hashset을 저장할때 interface로 전달하지 않고 type 을 전달해도 저장됩니다.
- 역직렬화 과정에서도 scan을 통해 HGetAll, MGet 등을 type으로 unmarshal 할 수 있습니다.
  Overview
  
  go-redis/v9 버전 이상에서 사용 가능한 기능들을 발견하여, 용례를 정리하고 성능 등 문제가 없는지 비교해봅니다.
  
  Usage
  
  go-redis/v8 이하
HashSet
- map interface를 만들어서 저장해야 한다.
- type을 만들어서 전달할 경우 아래의 에러 메세지를 받는다.
  - redis: can't marshal main.User (implement encoding.BinaryMarshaler) ```go

func populateDataV8(rdb *redisv8.Client, n int) { for i := 1; i <= n; i++ { user := User{ Name: fmt.Sprintf(“User%d”, i), Age: 20 + (i % 30), Email: fmt.Sprintf(“user%d@example.com”, i), Country: “Country” + strconv.Itoa(i%10), }

	userMap := map[string]interface{}{
		"name":    user.Name,
		"age":     user.Age,
		"email":   user.Email,
		"country": user.Country,
	}

	err := rdb.HSet(ctx, fmt.Sprintf("user:%d", i), userMap).Err()
	if err != nil {
		log.Fatalf("Failed to set user %d: %v", i, err)
	}
} }

- HGetAll
	- map interface로 전달받은 값을 map을 참조하여 결과를 구성
```go
func fetchDataV8(rdb *redisv8.Client, n int) {
	for i := 1; i <= n; i++ {
		fields, err := rdb.HGetAll(ctx, fmt.Sprintf("user:%d", i)).Result()
		if err != nil {
			log.Fatalf("Failed to get user %d: %v", i, err)
		}

		var user User
		user.Name = fields["name"]
		user.Age, _ = strconv.Atoi(fields["age"])
		user.Email = fields["email"]
		user.Country = fields["country"]
		// Print for debug purpose, comment out during benchmarking
		// fmt.Printf("user:%d - %+v\n", i, user)
	}
}

go-redis/v9 이상

HashSet
- type으로 생성된 결과를 그대로 전달해도 저장된다.
- string, int 여러 타입이 섞여 전달 될 수 있다. ```go for i := 1; i <= n; i++ { user := User{ Name: fmt.Sprintf(“User%d”, i), Age: 20 + (i % 30), Email: fmt.Sprintf(“user%d@example.com”, i), Country: “Country” + strconv.Itoa(i%10), }
  
  err := rdb.HSet(ctx, fmt.Sprintf(“user:%d”, i), user).Err() if err != nil { log.Fatalf(“Failed to set user %d: %v”, i, err) } }

- HGetAll
	- Scan 을 통해 타입에 맞도록 결과를 unmarshal 한다.
```go

func fetchDataV9(rdb *redisv9.Client, n int) {
	for i := 1; i <= n; i++ {
		res := rdb.HGetAll(ctx, fmt.Sprintf("user:%d", i))

		var user User
		if err := res.Scan(&user); err != nil {
			log.Fatalf("Failed to get user %d: %v", i, err)
		}
		// Print for debug purpose, comment out during benchmarking
		// fmt.Printf("user:%d - %+v\n", i, user)
	}
}

Benchmark

go-redis v8, v9의 hash저장, 조회 관련된 operation 을 수행하는 동작을 테스트한 결과는 아래와 같습니다.

v9이 v8에 비해 성능면에서는 다소 느려진 점이 있으나, 무시해도 될만한 수준의 차이입니다.

=== RUN   BenchmarkPopulateDataV8
BenchmarkPopulateDataV8
BenchmarkPopulateDataV8-10            20          57818098 ns/op           99482 B/op       2010 allocs/op
=== RUN   BenchmarkPopulateDataV9
BenchmarkPopulateDataV9
BenchmarkPopulateDataV9-10            21          67450760 ns/op           69820 B/op       2213 allocs/op
=== RUN   BenchmarkFetchDataV8
BenchmarkFetchDataV8
BenchmarkFetchDataV8-10               18          60724053 ns/op           67652 B/op       1716 allocs/op
=== RUN   BenchmarkFetchDataV9
BenchmarkFetchDataV9
BenchmarkFetchDataV9-10               18          62911891 ns/op           71903 B/op       2030 allocs/op

Conclusion

redis에 데이터를 저장할때, type을 지정해두고 값을 저장, 조회한다면 가독성과 코드 구조가 많이 개선될 수 있을 것 같습니다. 무조건 버전을 올리기보다, 필요한 기능으로 적용이 필요할때 올리면 좋을 것 같습니다.

References

https://github.com/redis/go-redis/issues/672
https://github.com/redis/go-redis/blob/f8cbf483f4a193d441fac2cf14be3d84783848c6/example_test.go#L281
https://github.com/redis/go-redis/discussions/2454
https://github.com/redis/go-redis

redis - cluster mode

Sat, 06 Jul 2024 00:00:00 +0000

redis cluster mode에 대해 이해하고, 현재 구성된 redis 환경 정보를 확인하는 방법에 대해 알아봅니다.

What is Cluster Mode?

redis 클러스터는 단순히 데이터 분할 전략 입니다. 여러 redis 노드에 걸쳐 데이터를 자동으로 분할합니다.

redis는 주노드(primary node)와 복제 노드(replica node)로 구성하는 것이 일반적이며, 이런 구성을 shard 로 여러 벌 준비하여 data partitioning이 될 수 있는 구성이 클러스터 모드(cluster mode) 입니다.

shading으로 데이터는 수평분할 어 저장됨에 따라 scale out, 단일 장애 지점(SPOF) 개선, 성능 향상 등의 이점을 얻을 수 있으며, 클러스터 구조에 따라 복잡성이 증가할 수 있으므로 상황에 따라 적절한 구조를 선택하는 것이 필요합니다. (출처:How to work with Cluster Mode on Amazon ElastiCache for Redis) aws article How to work with Cluster Mode on Amazon ElastiCache for Redis에서 다루고 있는 용어와 redis.io 문서에서 표현되는 용어가 미묘하게 다르지만, 위 이미지와 같이 비슷한 구조로 나누어 설명하고 있는것을 알 수 있습니다.

Redis Mode 별 차이 비교

aws article에서 각 mode별 구성에 대해 잘 정리한 표가 있어서 가져왔습니다. 앞서 언급한 내용과 같이 각각의 모드는 redis.io에서 언급하고 있는 standalone, sentienl, cluster mode와 유사한 범주로 언급하고 있음을 알 수 있습니다. (출처:How to work with Cluster Mode on Amazon ElastiCache for Redis)

수평 확장을 통해 성능상의 이점 등을 얻기 위해선 결국 data partitioning을 통한 sharding이 되어야 하는데, redis의 경우 hashslot을 통해 파티셔닝을 처리하는 것을 아래 그림에서 설명하고 있습니다. (출처:How to work with Cluster Mode on Amazon ElastiCache for Redis)

따라서 aws managed 서비스인 elastiCache를 사용하든 별도로 구성된 cluster mode를 사용하든 현재 구성된 클러스터 구조를 확인하고 이해하고 있어야 sharding을 통해 얻을수 있는 이점과, 관리 포인트를 이해하고 주의할 수 있을 것 입니다.

redis-cli로 cluster mode 환경 살펴보기

redis-cli를 설치하려면 환경에 맞게 링크 에서 확인하고 설치해줍니다.

현재 실행된 환경을 확인하는 방법은 다음과 같습니다.

# Connect to Redis server
$ redis-cli -h 127.0.0.1 -p 6379
# Check if cluster mode is enabled
CONFIG GET cluster-enabled
# Get all configuration settings
CONFIG GET *
# Get cluster nodes information
CLUSTER NODES
# Get cluster info
CLUSTER INFO

standalone 모드로 실행한 경우 아래와 같이 표시됩니다.

127.0.0.1:6379> CONFIG GET cluster-enabled
1) "cluster-enabled"
2) "no"

aws elastiCache로 redis cluster를 구성한 경우 아래와 같은 방법으로 정보를 확인할 수 있습니다.

xxx.cache.amazonaws.com:6379> CLUSTER INFO
cluster_state:ok
cluster_slots_assigned:16384
cluster_slots_ok:16384
cluster_slots_pfail:0
cluster_slots_fail:0
cluster_known_nodes:2
cluster_size:1
...

xxx.cache.amazonaws.com:6379> CLUSTER NODES
{slave-node-id} 192.168.xxx.xxx:6379@1122 slave {master-node-id} 0 1720327133306 5 connected
{master-node-id} 192.168.xxx.xxx:6379@1122 myself,master - 0 1700412779000 5 connected 0-16383

References

https://aws.amazon.com/ko/blogs/database/work-with-cluster-mode-on-amazon-elasticache-for-redis/
https://ot-container-kit.github.io/redis-operator/guide/setup.html?ref=breezymind.com#redis-cluster
https://www.digitalocean.com/community/tutorials/understanding-database-sharding

redis - key rules

Sun, 30 Jun 2024 00:00:00 +0000

TL; DR

계층 구조를 표현하기 위한 delimiter를 정합니다 (“:”)
쉽게 이해 가능하기 위한 길이로 key를 구성합니다.

Keyspace

Redis 키는 binary safe합니다. 즉, “foo”와 같은 문자열부터 JPEG 파일의 내용까지 모든 바이너리 시퀀스를 키로 사용할 수 있으며, 빈 문자열도 유효한 키입니다.

매우 길거나, 짧은 키는 좋지 않습니다.
- “user:1000:followers”와 “u1000flw”를 비교하자면 “user:1000:followers” 이 더 나은 옵션이며 적절한 키 길이의 균형을 잡는것이 필요합니다.
스키마를 고수하려고 노력하세요.
- 예를 들어 “object-type:id”는 “user:1000”처럼 좋은 아이디어입니다. .이나 -는 “comment:4321:reply.to” 또는 “comment:4321:reply-to”처럼 여러 단어로 구성된 필드에 자주 사용될 수 있습니다.
허용되는 최대 키 크기는 512MB입니다.

Kong Gateway 4. Kong Auth Plugin 연동하기

Sat, 18 Sep 2021 00:00:00 +0000

Kong, Plugin, Authorization에 대한 설명 및 구성 과정을 설명합니다.

Kong Gateway #4 Kong Auth Plugin 연동

0. 들어가기 전에

kong gateway는 기본적으로 인증 관련된 플러그인들을 기본적으로 제공합니다. 인증 및 인가에 대해서 간단히 알아보고 kong이 제공하는 몇가지 인증 플러그인들을 사용해보고 그 과정을 기술해보려고 합니다. consumer나 upstream 등을 상세하게 설정할 수 있으나, 본 글에서는 사용법과 과정을 살펴보는 것이 주된 목적이므로 자세한 과정을 생략함을 말씀드립니다.

1. Authentication(인증) vs Authorization(인가)

인증과 인가에 대한 용어는 많이들 헷갈리곤 합니다. 주로 인증을 이야기할때 인가를 포함하여 이야기하는 경우가 많은 것 같습니다. 따라서 조금 헷갈리시는 분들은 링크 글을 읽어보시면 이해하시는데 많은 도움이 될 것 같습니다.

이 글에서는 간단한 이해를 돕기 위해 짧은 설명을 덧붙이도록 하겠습니다.

Authentication(인증)은 회원 로그인과 같은 절차를 통해 해당 사용자에 대한 신원 확인을 하는 과정을 의미합니다. 보통 Google의 로그인 화면과 같이 사용자의 정보를 바탕으로 접근 가능한 사용자인지를 인증합니다.

Authorization(인가)은 인증 과정에서 해당 어느 기능들을 사용할 수 있는지에 대한 권한을 확인하고 인가하는 과정을 의미합니다.

2. 인증 및 인가 과정

여러 인증 방식중에 풍부한 스펙을 가진 OAuth2.0을 설명하기 위한 글에 포함된 그림 중 일부를 발췌해 설명하도록 하겠습니다. 참고로 OAuth2.0은 여러 grant type에 따라 인증 절차가 다양합니다. 이에 대해서는 자세히 다루지 않고 생략하며, 조금 추상적인 단계로 설명을 이어나가보도록 하겠습니다.

최종 목적은 Client가 ResourceServer에 접근하는 것이 목표이며, 이를 위해 Resource Server에 접근을 하기 위한 필수 조건인 token을 발급받는 과정이 필요합니다.

1,2번 과정을 통해 client는 로그인 혹은 사용자 정보를 통해 인증을 진행합니다. [인증]
3번 과정을 통해 인증이 성공할 경우, ResourceOwner(사용자) 에게 특정 권한에 허용해도 괜찮은지 허락을 구합니다. [인가]
4번 과정으로 client에게 Resource에 접근 가능한 토큰을 부여합니다.

위 흐름은 대략적인 내용이고, 인증 유형에 따라 달라지는 내용이라고 할 수 있습니다. 하지만 추상화된 단계로 살펴보면 client는 인증 서버에게 “로그인” 과 같은 절차를 통해 사용자 정보를 전달하고 유효한 사용자 정보라면

해당 사용자가 어떤 리소스에 접근 가능한지를 인가하는 과정을 거쳐 토큰을 받습니다.

그리고 그 토큰은 Resource Server에 접근 가능하기 위한 필수 요건이 됩니다.

이 과정은 OAuth에 대한 인증/인가 과정이며, 인증 유형에 따라 조금씩 다를 수 있다는 것을 다시 한번 말씀드립니다.

이후 살펴볼 플러그인 테스트는 kong에 사용자 인증 정보를 미리 등록시켜놓고 (ID/PW, API Key 등) API 서비스와 연동시키는 과정과 clinet가 해당 인증 정보를 바탕으로 요청하는 방법에 대해서 기술하려고 합니다.

3. 인증 플러그인 종류

위 사진은 konga 에서 캡쳐한 사진으로 kong에서 기본적으로 제공하는 Authentication 플러그인들을 보여줍니다. 이 중에 몇가지를 선택하여 사용하는 과정을 다뤄보겠습니다.

더 많은 플러그인들은 공식 홈페이지 플러그인 리스트 에서 확인 가능하며, 이후 다른 글에서 custom plugin 등을 구성하고 연동하는 과정도 다뤄보도록 하겠습니다.

4. 기본 제공 플러그인 연동

4.1. 사용할 예제 및 준비

이전 글에서도 사용했던 이미지를 가져왔습니다. 보통은 api gateway 내부의 upstream 서버로 요청하는 시나리오가 적당하지만, 기능을 테스트 하는것에 목적을 두기 위해 쉬운 예제로 google.com, naver.com. daum.net으로 요청하는 API를 두고 설명해보도록 하겠습니다.

konga를 통해 API Routing 구성 글 를 참고하시면 기본 설정을 마치실 수 있습니다.

또한 Kong admin API로도 구성할 수 있지만, 이해를 돕기 위해 Konga 툴로 이용해 진행하는 과정을 기술하겠습니다.

아래 절차들은 konga 화면에서 Routes - Plugins 화면에서 플러그인들을 추가할 수 있습니다.

또한 인증 과정은 앞서 말씀드린 내용처럼 요청자의 신원을 확인할 수 있어야 하는데, 예상되는 요청자를 Consumer를 통해 등록할 수 있습니다. 예를들어 G 라는 Consumer를 등록해놓으면, G만 Google 에 요청할 수 있도록 token을 발급해주는 과정을 말합니다.

위 사진처럼 G, K, N Consumer를 미리 구성해둡니다.

생성 후 해당 Consumer에게 적용할 Credentials를 설정할 수 있는데, 이 글에선 Basic, API Keys, HMAC 을 각각 Naver, Kakao, Google에 적용해보도록 할 예정입니다.

4.2. 인증 유형별 요청 방법

인증 플러그인들을 원하는 서비스에 붙일 경우 client가 요청하는 방법들이 각각 다릅니다. 이후 단계를 진행하기에 앞서 각 인증별로 정보를 전달하는 방법을 참고하시면 좋을 것 같습니다.

basic-auth

header 방식 - ex) Authorization: Basic dGVzdDphc2Rm

basic auth header generator

key-auth

query param 방식 등 - ex) ?apikey=dGVzdDphc2Rm

hmac-auth

header 방식 - ex) Authorization : hmac username=”hmac-test”,algorithm=”hmac-sha1”,headers=”X-Date”,signature=”089b8fcf36ce5bae9ccea9ad588609964a640f2e”

hmac auth header generator

jwt

header 방식 - ex) Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9….

jwt auth header generator

oauth2

header 및 query param 방식

https://konghq.com/blog/kong-gateway-oauth2/

4.3 Basic Auth 테스트

아래 절차대로 N 이라는 consumer가 Naver라는 서비스에 요청하기 위한 기본 설정을 하도록 하겠습니다.

Consumers → N → Credentials → Basic → Create Credentials

위와 같이 입력해줍니다.

Naver service에 가서 플러그인을 설정해주고, Eligible consumers 도 확인해줍니다.

이렇게 설정된 API로 요청해보도록 합니다.

요청

curl {kong address}/naver

응답

{
  "message":"Unauthorized"
}

basic auth header generator 사이트에서 Authorization 헤더에 포함시킬 정보를 생성해보도록 합니다.

요청

curl {kong address}/naver -H "Authorization: Basic bmF2ZXItdGVzdDoxMjM0"

응답

<html>
<head><title>301 Moved Permanently</title></head>
<body>
<center><h1>301 Moved Permanently</h1></center>
<hr><center> NWS </center>
</body>
</html>

4.4 API Key 테스트

아래 절차대로 K 이라는 consumer가 Kakao라는 서비스에 요청하기 위한 기본 설정을 하도록 하겠습니다.

Consumers → K → Credentials → API Keys→ Create Credentials

플러그인을 붙일때 아무 값도 입력하지 않으면 다음 정보가 기본으로 입력됩니다.

요청

curl {kong address}/kakao

응답

{
  "message":"No API key found in request"
}

요청

curl {kong address}/kakao?apikey=test-api-key

응답

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>302 Found</title>
</head><body>
<h1>Found</h1>
<p>The document has moved <a href="http://www.daum.net/?apikey=test-api-key">here</a>.</p>
</body></html>

4.5 HMAC 테스트

아래 절차대로 G 이라는 consumer가 Google라는 서비스에 요청하기 위한 기본 설정을 하도록 하겠습니다.

Consumers → G → Credentials → HMAC → Create Credentials

플러그인을 붙일때 아무 값도 입력하지 않으면 다음 정보가 기본으로 입력됩니다.

hmac auth header generator 사이트에서 Authorization 헤더에 포함시킬 정보를 생성해보도록 합니다.

요청

curl {kong address}/google

응답

{
  "message":"Unauthorized"
}

요청

curl {kong address}/google -H 'Authorization : hmac username="hmac-test",algorithm="hmac-sha1",headers="X-Date",signature="089b8fcf36ce5bae9ccea9ad588609964a640f2e"'

응답

<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8">
<TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>
The document has moved
<A HREF="https://www.google.com/">here</A>.
</BODY></HTML>

5. 정리

인증/인가 과정은 OpenAPI로 구성하거나 client들에게 제한된 기능을 제공해야 할 경우 필수적인 요소입니다.

또한 Resource Server나 API Server에 접근 가능한 token/API Key 등이 유출되면 비용을 지불하지 않고 요청하거나 예상되지 않은 경로 등으로 API를 요청할 수 있게 되어 보안상 문제가 발생합니다.

따라서 보다 안정된 유형의 인증 서비스를 제공하려고 한다면 고정된 API Key 등으로 client에게 제공하기 보다, 토큰의 발급/갱신/삭제 등을 처리하는 인증/인가 기능이 필요합니다.

기회가 된다면 다음 글에서 custom plugin 구성과 안정화된 인증을 적용해보는 과정을 기술해보도록 하겠습니다.

6. 참고

https://howtogapps.com/google-script-authorization-review-and-accept-the-permission-guide/

https://developer.okta.com/blog/2017/06/21/what-the-heck-is-oauth

https://docs.konghq.com/hub/

ArgoCD 2. ArgoCD Slack Notification

Sat, 17 Jul 2021 00:00:00 +0000

Argocd Slack Notification 구성 과정을 설명합니다.

0. 들어가기 전에

ArgoCD 구성 이후 Sync 동작이 완료되거나 문제가 있을 경우 Slack으로 notification을 전달하고 싶었습니다. 하지만 공식 가이드 대로 진행하니 잘 동작하지 않았습니다. 꽤 불필요한 시간을 소비했고, 다시 정리하면서 문제를 해결하고 과정을 기록하고자 합니다.

또한 ArgoCD 공식 notifiaction 이외에도 ArgoCD 가 제안하는 다른 방식으로도 notification을 구성할 수 있습니다.

가장 star 수가 많은 kubewatch로 K8S deploy 상태를 확인하여 slack webhook으로 전달하는 것은 어렵지 않게 성공할 수 있었으나, argo sync의 성공 여부를 판단하여 notification을 주고 싶었기 때문에 ArgoCD 공식 notification을 다시 짚어보기로 결정했습니다.

1. 문제의 발생

공식 가이드 대로 notification을 구성하니 잘 동작하지 않았습니다. 다시 천천히 문서를 살펴보니 helm 설치 관련된 내용이 하단부에 있었습니다. 이 글에 따르면 아래와 같이 helm v3으로 notification을 쉽게 구성할 수 있다고 가이드하고 있지만 결과는 잘 동작하지 않습니다.

helm repo add argo https://argoproj.github.io/argo-helm
helm install argo/argocd-notifications --generate-name \
    --set triggers[0].name=on-sync-succeeded \
    --set triggers[0].enabled=true \
    --set secret.notifiers.slack.enabled=true \
    --set secret.notifiers.slack.token=<my-token>

Error: YAML parse error on argocd-notifications/templates/configmap.yaml: error converting YAML to JSON: yaml: line 15: did not find expected key

https://github.com/argoproj/argo-helm/issues/616 이 글에도 같은 문제가 있는데 글 작성 기준으로 해결되지 않은 상태로 있습니다.

2. 처음부터 짚어보기

2.1 slack 봇 생성

공식 가이드 문서에도 이부분은 잘 나와있지만 지금 글 쓰는 시점에서의 slack api 화면 구성과 약간 다르기 때문에 몇가지 부분만 캡쳐한 내용을 올립니다. 하지만 가이드 문서 내용에 이슈는 없습니다.

https://api.slack.com/apps?new_app=1 화면으로 가서 아래와 같은 과정을 거칩니다.

app 생성하는 화면이 변경되었습니다. (21.07.17 기준) 이후에도 변경될 수 있지만 참고로 봐주시기 바랍니다.

Scopes는 필요하다고 생각되는 권한을 부여했고 OAuth Token 보면 공식 가이드는 xoxp로 시작하는데 xoxb로 생성되고 있으며 Bot Token Scopes로 권한을 주면 됩니다.

이렇게 권한을 부여한 뒤 원하는 workspace 및 channel로 Install 해줍니다.

slack 내 Integrations에 해당 앱이 추가되어 있지 않으면 알림이 오지 않습니다.

2.2 Kubernetes에 notifier 및 template 설치하기

공식 가이드 대로도 해보고 여러 글들을 찾아서 다 해봤는데, 정말 많은 시행착오 끝에 아래 내용으로 알람이 오는것을 확인했으며, 설치와 관련된 글은 링크를 확인하시기 바랍니다.

주의할점은 argocd가 설치된 namespace와 똑같은 공간에 notifier와 template 등을 설치하셔야 합니다.

2.2.1 argocd-notifications-secret.yaml (신규 생성)

apiVersion: v1
kind: Secret
metadata:
  name: argocd-notifications-secret
stringData:
  notifiers.yaml: |
    slack:
      token: 

slack token은 앞서 발급받은 xoxb로 시작하는 oauth token을 입력합니다. ( 까지 지워야 합니다.)

kubectl apply -f argocd-notifications-secret.yaml -n argocd

2.2.2 notification.yaml

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/manifests/install.yaml

공식 가이드에선 위 내용을 바로 apply 하라고 나오는데, 반영 후 아래 내용을 추가해도 좋고 제가 수정 반영해놓은 반영된 전체 yaml 파일을 복사하셔서 apply 해도 됩니다.

apiVersion: v1
kind: ConfigMap
metadata:
  creationTimestamp: null
  name: argocd-notifications-cm
data:
  config.yaml: |
    triggers:
      - name: on-sync-succeeded
        enabled: true

반영된 전체 yaml 파일

apiVersion: v1
kind: ServiceAccount
metadata:
  name: argocd-notifications-controller
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: argocd-notifications-controller
rules:
- apiGroups:
  - argoproj.io
  resources:
  - applications
  - appprojects
  verbs:
  - get
  - list
  - watch
  - update
  - patch
- apiGroups:
  - ""
  resources:
  - secrets
  - configmaps
  verbs:
  - get
  - list
  - watch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: argocd-notifications-controller
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: argocd-notifications-controller
subjects:
- kind: ServiceAccount
  name: argocd-notifications-controller
---
apiVersion: v1
kind: ConfigMap
metadata:
  creationTimestamp: null
  name: argocd-notifications-cm
data:
  config.yaml: |
    triggers:
      - name: on-sync-succeeded
        enabled: true
---
apiVersion: v1
kind: Secret
metadata:
  name: argocd-notifications-secret
type: Opaque
---
apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/name: argocd-notifications-controller-metrics
  name: argocd-notifications-controller-metrics
spec:
  ports:
  - name: metrics
    port: 9001
    protocol: TCP
    targetPort: 9001
  selector:
    app.kubernetes.io/name: argocd-notifications-controller
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: argocd-notifications-controller
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: argocd-notifications-controller
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        app.kubernetes.io/name: argocd-notifications-controller
    spec:
      containers:
      - command:
        - /app/argocd-notifications-backend
        - controller
        image: argoprojlabs/argocd-notifications:v1.0.2
        imagePullPolicy: Always
        name: argocd-notifications-controller
        volumeMounts:
        - mountPath: /app/config/tls
          name: tls-certs
        workingDir: /app
      securityContext:
        runAsNonRoot: true
      serviceAccountName: argocd-notifications-controller
      volumes:
      - configMap:
          name: argocd-tls-certs-cm
        name: tls-certs

kubectl apply -f notification.yaml -n argocd

2.2.3 templates.yaml

공식 가이드에선 위 내용을 바로 apply 하라고 합니다. 위 내용을 내려받으면 특정 조건에서 동작할 메세지 등이 정의된 내용을 확인할 수 있습니다.

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/catalog/install.yaml

위 내용을 내려받은 yaml 파일

apiVersion: v1
data:
  template.app-deployed: |
    email:
      subject: New version of an application  is up and running.
    message: |
      :white_check_mark: Application  is now running new version of deployments manifests.
    slack:
      attachments: |
        [{
          "title": "",
          "title_link":"/applications/",
          "color": "#18be52",
          "fields": [
          {
            "title": "Sync Status",
            "value": "",
            "short": true
          },
          {
            "title": "Repository",
            "value": "",
            "short": true
          },
          {
            "title": "Revision",
            "value": "",
            "short": true
          }
          
          ,
          ,
          {
            "title": "",
            "value": "",
            "short": true
          }
          
          ]
        }]
  template.app-health-degraded: |
    email:
      subject: Application  has degraded.
    message: |
      :exclamation: Application  has degraded.
      Application details: /applications/.
    slack:
      attachments: |-
        [{
          "title": "",
          "title_link": "/applications/",
          "color": "#f4c030",
          "fields": [
          {
            "title": "Sync Status",
            "value": "",
            "short": true
          },
          {
            "title": "Repository",
            "value": "",
            "short": true
          }
          
          ,
          ,
          {
            "title": "",
            "value": "",
            "short": true
          }
          
          ]
        }]
  template.app-sync-failed: |
    email:
      subject: Failed to sync application .
    message: |
      :exclamation:  The sync operation of application  has failed at  with the following error: 
      Sync operation details are available at: /applications/?operation=true .
    slack:
      attachments: |-
        [{
          "title": "",
          "title_link":"/applications/",
          "color": "#E96D76",
          "fields": [
          {
            "title": "Sync Status",
            "value": "",
            "short": true
          },
          {
            "title": "Repository",
            "value": "",
            "short": true
          }
          
          ,
          ,
          {
            "title": "",
            "value": "",
            "short": true
          }
          
          ]
        }]
  template.app-sync-running: |
    email:
      subject: Start syncing application .
    message: |
      The sync operation of application  has started at .
      Sync operation details are available at: /applications/?operation=true .
    slack:
      attachments: |-
        [{
          "title": "",
          "title_link":"/applications/",
          "color": "#0DADEA",
          "fields": [
          {
            "title": "Sync Status",
            "value": "",
            "short": true
          },
          {
            "title": "Repository",
            "value": "",
            "short": true
          }
          
          ,
          ,
          {
            "title": "",
            "value": "",
            "short": true
          }
          
          ]
        }]
  template.app-sync-status-unknown: |
    email:
      subject: Application  sync status is 'Unknown'
    message: |
      :exclamation: Application  sync is 'Unknown'.
      Application details: /applications/.
      
      
          * 
      
      
    slack:
      attachments: |-
        [{
          "title": "",
          "title_link":"/applications/",
          "color": "#E96D76",
          "fields": [
          {
            "title": "Sync Status",
            "value": "",
            "short": true
          },
          {
            "title": "Repository",
            "value": "",
            "short": true
          }
          
          ,
          ,
          {
            "title": "",
            "value": "",
            "short": true
          }
          
          ]
        }]
  template.app-sync-succeeded: |
    email:
      subject: Application  has been successfully synced.
    message: |
      :white_check_mark: Application  has been successfully synced at .
      Sync operation details are available at: /applications/?operation=true .
    slack:
      attachments: "[{\n  \"title\": \"\",\n  \"title_link\":\"/applications/\",\n  \"color\": \"#18be52\",\n  \"fields\": [\n  {\n    \"title\": \"Sync Status\",\n    \"value\": \"\",\n    \"short\": true\n  },\n  {\n    \"title\": \"Repository\",\n    \"value\": \"\",\n    \"short\": true\n  }\n  \n  ,\n  ,\n  {\n    \"title\": \"\",\n    \"value\": \"\",\n    \"short\": true\n  }\n  \n  ]\n}]    "
  trigger.on-deployed: |
    - description: Application is synced and healthy. Triggered once per commit.
      oncePer: app.status.sync.revision
      send:
      - app-deployed
      when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy'
  trigger.on-health-degraded: |
    - description: Application has degraded
      send:
      - app-health-degraded
      when: app.status.health.status == 'Degraded'
  trigger.on-sync-failed: |
    - description: Application syncing has failed
      send:
      - app-sync-failed
      when: app.status.operationState.phase in ['Error', 'Failed']
  trigger.on-sync-running: |
    - description: Application is being synced
      send:
      - app-sync-running
      when: app.status.operationState.phase in ['Running']
  trigger.on-sync-status-unknown: |
    - description: Application status is 'Unknown'
      send:
      - app-sync-status-unknown
      when: app.status.sync.status == 'Unknown'
  trigger.on-sync-succeeded: |
    - description: Application syncing has succeeded
      send:
      - app-sync-succeeded
      when: app.status.operationState.phase in ['Succeeded']
kind: ConfigMap
metadata:
  creationTimestamp: null
  name: argocd-notifications-cm

kubectl apply -f templates.yaml -n argocd

2.3 트리거 등록

트리거들은 아래와 같은 종류들이 있고, 두가지 방법으로 등록 할 수 있습니다.

notifications.argoproj.io/subscribe.on-created.slack
notifications.argoproj.io/subscribe.on-delete.slack
notifications.argoproj.io/subscribe.on-deployed.slack
notifications.argoproj.io/subscribe.on-health-degraded.slack
notifications.argoproj.io/subscribe.on-sync-failed.slack
notifications.argoproj.io/subscribe.on-sync-running.slack
notifications.argoproj.io/subscribe.on-sync-status-unknown.slack
notifications.argoproj.io/subscribe.on-sync-succeeded.slack

2.3.1 kubectl 로 argo app에 annotation을 추가하는 방법

<app-name>, <notifications.argoproj.io/subscribe.on-sync-succeeded.slack>, <slack-channel-name> 를 각각 <> 빼고 원하는 값을 넣습니다.

kubectl patch app <app-name> -n argocd -p '{"metadata": {"annotations": {"<notifications.argoproj.io/subscribe.on-sync-succeeded.slack>":"<slack-channel-name>"}}}' --type merge

2.3.2 argocd admin 페이지에서 annotation을 추가하는 방법

3. Trouble shooting

3.1 argocd-notifications-controller pod의 로그

time="2021-07-13T07:40:48Z" level=info msg="Start processing" app=argocd/notifier
time="2021-07-13T07:40:48Z" level=info msg="Trigger on-sync-succeeded result: [{[0].zxM90Et6k4Elb1-fHdjtDJq0xR0  [app-sync-succeeded] true}]" app=argocd/notifier
time="2021-07-13T07:40:48Z" level=info msg="Sending notification about condition 'on-sync-succeeded.[0].zxM90Et6k4Elb1-fHdjtDJq0xR0' to '{slack notifier}'" app=argocd/notifier
time="2021-07-13T07:40:48Z" level=error msg="Failed to notify recipient {slack notifier} defined in app argocd/notifier: notification service 'slack' is not supported" app=argocd/notifier

위 내용은 slack token / slack 채널에 bot 초대 / slack 채널명 상이 등과 관련 있습니다.

3.2 argocd app이 보이지 않는 경우

kubectl get app -n argocd

rancher 구성 혹은 다른 문제로 인해 위 결과가 표시되지 않을 경우, 2.3.1 트리거 방법을 사용할 수 없고

2.3.2 방법으로 트리거를 등록해야 합니다.

4. 정리

혹시 3. Trouble shooting 내용과 유사한 문제가 있거나, 의도한대로 notification 연동이 되지 않는다면 2. 처음부터 짚어보기 부분을 참고하시길 바랍니다. 가이드 문서가 여러군데로 나뉘어있고, 다른 글들에서도 조금씩 방법을 다르게 정리해 놓았는데, 위 방법으로 진행하고 나서 slack 알람이 오는 것을 확인하였습니다.

혹시나 도저히 연동이 안되어서 스트레스 받는 분이 계시다면 kubewatch로 구성하는 것이 문제없이 연동되었습니다.

5. 참고자료

https://argocd-notifications.readthedocs.io/en/stable/services/slack/

ArgoCD 1. ArgoCD 구성하기

Sat, 17 Jul 2021 00:00:00 +0000

Argocd 구성 과정을 설명합니다.

0. 들어가기 전에

계속해서 Kuberentes 내에서의 infra 구성에 대한 글을 정리하고 있습니다. 이번 글도 마찬가지이며 웹 상에 공식 페이지 및 많은 글들이 구성 방법에 대해 설명하고 있지만 하나 두개씩 가이드와 다르거나 동작하지 않는 경우들을 심심치 않게 볼 수 있었습니다.

그러한 이유로 이 글을 작성하기로 마음먹은 이유도 있습니다. 혹시나 같은 경우를 겪는 누군가에게 도움이 되길 바라며 글을 시작하겠습니다.

이 글은 DevOps, GitOps, Helm 및 Kustomize 등 manifest에 대한 전반에 대해 이해하고 있다고 가정하며 자세하게 다루지는 않으며, Kubernetes 환경에서 진행됨을 말씀드립니다.

1. CD in DevOps

https://programmerblog.net/what-is-devop/

https://www.opsera.io/blog/top-25-devops-tools-that-you-need-to-know

위 그림에서 보이는 DevOps 과정 중에서 오른쪽에 붉게 표시된 argoCD를 이용해 CD를 구성하게 될 것입니다. 향후 기회가 된다면 CI까지 연동해 Dev Ops 전체 과정이 부드럽게 이어져 동작하는 것을 공유드릴 수 있으면 좋겠습니다.

2. ArgoCD

공식 문서를 참고하면 ArgoCD에 대해 이렇게 설명하고 있습니다.

Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes

Application definitions, configurations, and environments should be declarative and version controlled. Application deployment and lifecycle management should be automated, auditable, and easy to understand.

정리해서 기술하자면 ArgoCD는 Devops과정 중 Kuberenetes 환경에서 Continuous Deploy 의 부분을 담당하는 도구라고 볼 수 있습니다.

Helm 및 Kustomize 의 manifest 구성을 GitOps 저장소에 반영하면 ArgoCD가 변경점을 체크하여 Deploy를 자동으로 진행합니다. 언급된 내용처럼 직관적으로 Deployment와 Pod 등의 구성을 확인할 수 있고, rollback 등도 UI로 쉽게 진행할 수 있습니다.

3. CD 구성

3.1 GitOps 구성

GitOps를 위해 Git repository가 필요합니다. GitOps 동작에 대한 내용은 weaveworks - Operations by Pull Request을 참고하시면 도움될 것 같습니다.

Git 기반의 repository들을 GitOps로 활용할 수 있고, AWS code commit, Github 등 어느 것을 사용하더라도 argoCD와 연동할 수 있습니다.

혹시 github를 사용하신다면, github repo를 하나 생성하고 테스트할 helm chart를 넣어둡니다.

본 글의 내용을 모두 진행하게 되면 Kubernetes 로의 배포는 위와 같은 그림으로 진행될 것입니다. User가 PR 하는 내용은 helm 등으로 구성된 K8S 구성 manifest이며 PR 이후 argoCD가 변경점을 보고 있다가, K8S에 반영하게 됩니다.

3.2 ArgoCD 설치

ArgoCD를 설치하는 과정은 공식 홈페이지에 잘 기술되어 있습니다.

3.2.1 Kubernetes에 ArgoCD 설치

설치

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

외부에서 접근 가능하도록 Service type 변경 (node port 변경 후 port fowrding도 가능)

kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'

3.2.2 admin 계정 설정

가이드에서 언급하고 있는대로 ArgoCD cli로 admin 계정 비밀번호를 설정하면 로그인 되지 않았습니다.

argoproj의 이슈 에서 이미 언급된 내용이 있고, password가 일치하지 않는 문제가 발생하였습니다.

위 이슈의 내용 아래 명령으로 비밀번호를 변경할 수 있었고 (newpassword 부분을 원하는 것으로 변경), ArgoCD cli로 비밀번호만 변경할 목적이라면 사실 cli 설치 자체가 필요하지 않다고 생각되어 본 글에선 생략합니다.

kubectl patch secret -n argocd argocd-secret \
  -p '{"stringData": { "admin.password": "'$(htpasswd -bnBC 10 "" newpassword | tr -d ':\n')'"}}'

환경에 htpasswd 가 없는 경우 아래 명령으로 설치해줍니다. (ubuntu)

apt install apache2-utils

4. ArgoCD 살펴보기

4.1 ArgoCD 접속

$ kubectl get svc -n argocd
NAME                                      TYPE           CLUSTER-IP       EXTERNAL-IP                                                                    PORT(S)                      AGE
argocd-dex-server                         ClusterIP      172.20.234.216   <none>                                                                         5556/TCP,5557/TCP,5558/TCP   44d
argocd-metrics                            ClusterIP      172.20.19.60     <none>                                                                         8082/TCP                     44d
argocd-notifications-controller-metrics   ClusterIP      172.20.34.41     <none>                                                                         9001/TCP                     3d20h
argocd-redis                              ClusterIP      172.20.246.35    <none>                                                                         6379/TCP                     44d
argocd-repo-server                        ClusterIP      172.20.119.15    <none>                                                                         8081/TCP,8084/TCP            44d
argocd-server                             LoadBalancer   172.20.138.97    xxx.ap-northeast-2.elb.amazonaws.com   80:30462/TCP,443:31008/TCP   44d
argocd-server-metrics                     ClusterIP      172.20.231.166   <none>                                                                         8083/TCP                     44d

LoadBalancer 타입으로 변경한 경우 지정된 nlb 주소 (xxx.ap-northeast-2.elb.amazonaws.com) 로 브라우저에서 접속해봅니다.

4.2 Argo App 구성

앞 단계에서 설정한 admin 계정 정보를 넣습니다.

접속해서 보이는 화면에서 helm 혹은 kustomize로 구성된 manifest가 존재하는 git repositiory를 등록 준 뒤 첫번째 탭을 선택하여 NewApp 버튼으로 연결된 repository의 helm chart를 연결합니다.

이제 gitops repository로 가서 values.yaml 등으로 원하는 부분을 변경 후 push 하면

위 화면처럼 Sync 기능을 통해 gitops repository와 현재 클러스터의 차이를 확인하여 변경점이 있을 경우 gitops repository의 helm chart 구성을 바탕으로 배포하게 됩니다.

해당 앱의 구조 파악 및 이전 버전으로의 rollback 등을 손쉽게 UI로 처리할 수 있습니다.

5. 정리

이번 글은 사실 많은 내용은 없습니다. 다만 공식 가이드에서 제공해준 내용대로 진행하다가 admin 계정 설정 부분에서 잘 안되었던 부분이 있어, 관련 내용을 기술하고자 ArgoCD와 관련된 내용도 일부 정리하게 되었습니다.

6. 참고자료

https://argoproj.github.io/argo-cd/

https://programmerblog.net/what-is-devop/

https://www.opsera.io/blog/top-25-devops-tools-that-you-need-to-know

Kong Gateway 3. Kong Admin 으로 API 구성하기

Sun, 11 Jul 2021 00:00:00 +0000

Kong, Kong Admin에 대한 설명 및 구성 과정을 설명합니다.

0. 들어가기 전에

이전 장에서 Kong API Gateway와 Konga를 K8S에서 구성하여 API 간단히 테스트 해봤습니다. 하지만 Kong의 많은 기능들을 제대로 이해하기 위해 공식 문서를 통해 하나씩 살펴보는 것이 필요하겠다라는 생각이 들었습니다.

아래 과정들은 konga를 설치하면 UI로 쉽게 구성할 수 있지만, konga를 사용하지 않는 경우도 있고, infra code로 관리하게 될 경우 기본이되는 REST 구성을 살펴보기 위해 Kong Admin API 를 통해 API 구성을 해본 과정을 기술합니다.

혹시 Kong 환경이 구성되지 않으셨다면 이 글을 참고하시기 바랍니다.

1. Kong Gateway

앞서 이야기한 내용처럼 Kong Gateway는 Nginx 기반으로 Gateway 기능을 수행하기 위한 목적으로 만들어 졌습니다. Kong은 Reverse Proxy로 많이 쓰이는 Nginx 위에 Lua 언어로 플러그인들이 구성되어 Reverse Proxy의 기능 외에도 API Gateway가 갖춰야 할 다양한 기능들을 제공합니다.

Micro Service Architecture 로 시스템을 설계함에 있어 Kong은 다양한 plugin 구성으로 큰 장점을 가져올 수 있다고 말하고 있으며 Kong Gateway as a paragon of microservice architecture 라고 kong 문서에서 이야기하고 있습니다.

2. Getting Started Guide

2.1 Overview

kong gateway 서비스는 Enterprise와 OSS(OpenSource) 구성으로 나누어져 있습니다. 이 글에서 살펴볼 내용은 OSS 에 해당하는 부분입니다. 청록색 부분이 Enterprise Version의 기능을 의미하는데, Kong Manager같은 경우 Konga 라는 kong admin을 UI로 관리할 수 있는 open source 대체 툴이 존재합니다.

https://docs.konghq.com/getting-started-guide/2.4.x/overview/

위 그림은 단순히 Kong에 대한 그림 뿐만 아니라 일반적인 API Gateway들의 특징들을 의미하기도 합니다.

API Client로부터 8000/8443 로 프록시된 포트로부터 요청을 받고 Backend API로 요청을 전달합니다. Admin의 경우 Restful 방식으로 여러 설정들을 구성할 수 있는데 helm으로 구성할 경우 기본적으로 8001로 expose 되어있습니다.

따라서 kubectl get service 명령을 통해 port가 어떻게 포워딩 되어있는지 확인하시길 바랍니다.

2.2 Prepare to Administer

링크 의 원글을 실험해보면서 해당 과정을 조금 더 자세히 이해해보도록 하겠습니다.

NAME                             TYPE           CLUSTER-IP       EXTERNAL-IP                                                                    PORT(S)                                                    AGE
konga                            LoadBalancer   172.20.163.27    xxx1.ap-northeast-2.elb.amazonaws.com   80:31458/TCP                                               19h
my-release-kong                  LoadBalancer   172.20.244.82    xxx2.ap-northeast-2.elb.amazonaws.com   80:31067/TCP,443:32020/TCP,8001:31014/TCP,8444:31241/TCP   19h
my-release-kong-metrics          ClusterIP      172.20.109.139   <none>                                                                         9119/TCP                                                   19h
my-release-postgresql            ClusterIP      172.20.17.148    <none>                                                                         5432/TCP                                                   19h
my-release-postgresql-headless   ClusterIP      None             <none>                                                                         5432/TCP                                                   19h

kubectl get svc -n default 명령을 통해 초기 kong, konga가 구성된 서비스들을 확인해볼 수 있습니다.

편의를 위해 konga, my-release-kong 두개를 LoadBalancer type으로 변경해 외부에서 요청할 수 있도록 LoadBalancer로 타입을 변경하여 elb를 붙였습니다.

지금은 my-release-kong 만 살펴볼 예정인데, 포트를 보면 80:31067/TCP, 443:32020/TCP, 8001:31014/TCP, 8444:31241/TCP 가 포워딩 된 것을 볼 수 있습니다.

이전 단계에서 언급했던 것 처럼 Admin은 8001, API 요청은 80(8000), 443(8443), 으로 요청을 받아주도록 구성되었습니다.

2.2.1 Admin API 테스트

공식 문서의 위 항목 중 여기서는 OSS의 Spec을 살펴 볼 것이므로 Using the Admin API를 선택합니다.

요청

curl -i -X GET xxx2.ap-northeast-2.elb.amazonaws.com:8001

응답

위 결과처럼 응답이 내려오는데 API Gateway 설정과 관련된 굉장히 많은 정보를 포함하고 있으므로 응답 전문은 생략합니다.

2.3 Expose your Services

여기서 Service 와 Route라는 개념을 다룹니다.

Service is an entity representing an external upstream API or microservice.

Routes determine how (and if) requests are sent to their Services after they reach Kong Gateway.

각각 정리된 내용을 살펴보면 Service는 upstream API 나 microservice 에 대한 정보를 포함하여 정의되고, Route는 그렇게 정의된 Service를 외부 요청으로부터 연결해준다고 불 수 있습니다.

그런 이유로 구성 순서는 Service 정의 → Route 연결 이 됩니다.

2.3.1 Add a Service

Using the Admin API를 선택해서 Service 등록 과정을 살펴봅니다.

조금 구성을 변경해서 google.com을 example_service의 이름을 갖는 서비스로 등록 해보도록 하겠습니다.

요청

curl -i -X POST http://xxx2.ap-northeast-2.elb.amazonaws.com:8001/services \
  --data name=example_service \
  --data url='https://google.com'

응답

{
  "port": 443,
  "name": "example_service",
  "client_certificate": null,
  "path": null,
  "ca_certificates": null,
  "write_timeout": 60000,
  "connect_timeout": 60000,
  "tls_verify": null,
  "protocol": "https",
  "tls_verify_depth": null,
  "host": "google.com",
  "created_at": 1623725919,
  "retries": 5,
  "id": "174a56d3-69b3-4211-afe2-e0405dc61ce4",
  "tags": null,
  "read_timeout": 60000,
  "updated_at": 1623725919
}

2.3.2 Add a Route

Using the Admin API를 선택해서 Route 등록 과정을 살펴봅니다.

여기서 살펴볼만한 점은 POST 주소를 보면 services/example_services/rotues 의 restful한 리소스 구조로 요청을 보내고 있는데, routes가 services 리소스에 종속되어 있음을 알 수 있습니다.

또한 —data 옵션으로 ‘paths[]=/mock’ 를 주고 있는데 사용자가 Kong API Gateway를 통해 요청할 때 /mock 로 보내면 example_service로 연결함을 의미합니다.

Route 등록

요청

curl -i -X POST http://xxx2.ap-northeast-2.elb.amazonaws.com:8001/services/example_service/routes \
  --data 'paths[]=/mock' \
  --data name=mocking

응답

{
  "name": "mocking",
  "paths": ["/mock"],
  "methods": null,
  "tags": null,
  "destinations": null,
  "request_buffering": true,
  "response_buffering": true,
  "strip_path": true,
  "service": { "id": "174a56d3-69b3-4211-afe2-e0405dc61ce4" },
  "https_redirect_status_code": 426,
  "preserve_host": false,
  "protocols": ["http", "https"],
  "regex_priority": 0,
  "path_handling": "v0",
  "created_at": 1623726177,
  "updated_at": 1623726177,
  "headers": null,
  "hosts": null,
  "id": "81580cf8-3a6c-4b37-95df-5e810f41b07e",
  "snis": null,
  "sources": null
}

2.3.3 연결 확인

아래 요청과 같이 보냅니다. 주의할 점은 저 처럼 helm으로 K8S 내 kong을 구성하면 기본으로 8000이 아니라 80으로 port forwarding 되어있습니다.

또 이전 API 등록 예제는 Admin(8001)로 보냈는데, 등록이 완료된 이후로는 Kong API Gateway(80/8000)으로 보내고 있음을 알 수 있습니다.

요청

curl -i -X GET http://xxx2.ap-northeast-2.elb.amazonaws.com:80/mock/request

응답

HTTP/1.1 404 Not Found
Content-Type: text/html; charset=UTF-8
Content-Length: 1568
Connection: keep-alive
Referrer-Policy: no-referrer
Date: Tue, 15 Jun 2021 03:08:24 GMT
Alt-Svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000,h3-T051=":443"; ma=2592000,h3-Q050=":443"; ma=2592000,h3-Q046=":443"; ma=2592000,h3-Q043=":443"; ma=2592000,quic=":443"; ma=2592000; v="46,43"
X-Kong-Upstream-Latency: 171
X-Kong-Proxy-Latency: 109
Via: kong/2.4.1

<!DOCTYPE html>
<html lang=en>
  <meta charset=utf-8>
  <meta name=viewport content="initial-scale=1, minimum-scale=1, width=device-width">
  <title>Error 404 (Not Found)!!1</title>
  <style>
    *{margin:0;padding:0}html,code{font:15px/22px arial,sans-serif}html{background:#fff;color:#222;padding:15px}body{margin:7% auto 0;max-width:390px;min-height:180px;padding:30px 0 15px}* > body{background:url(//www.google.com/images/errors/robot.png) 100% 5px no-repeat;padding-right:205px}p{margin:11px 0 22px;overflow:hidden}ins{color:#777;text-decoration:none}a img{border:0}@media screen and (max-width:772px){body{background:none;margin-top:0;max-width:none;padding-right:0}}#logo{background:url(//www.google.com/images/branding/googlelogo/1x/googlelogo_color_150x54dp.png) no-repeat;margin-left:-5px}@media only screen and (min-resolution:192dpi){#logo{background:url(//www.google.com/images/branding/googlelogo/2x/googlelogo_color_150x54dp.png) no-repeat 0% 0%/100% 100%;-moz-border-image:url(//www.google.com/images/branding/googlelogo/2x/googlelogo_color_150x54dp.png) 0}}@media only screen and (-webkit-min-device-pixel-ratio:2){#logo{background:url(//www.google.com/images/branding/googlelogo/2x/googlelogo_color_150x54dp.png) no-repeat;-webkit-background-size:100% 100%}}#logo{display:inline-block;height:54px;width:150px}
  </style>
  <a href=//www.google.com/><span id=logo aria-label=Google></span></a>
  <p><b>404.</b> <ins>That’s an error.</ins>
  <p>The requested URL <code>/request</code> was not found on this server.  <ins>That’s all we know.</ins>

구글로 부터 404 응답이 내려온 것을 확인할 수 있습니다.

2.4 Protect your Services

이 장에서는 API Gateway의 기능 중 Rate limit 을 살펴보도록 합니다. 조금 당연한 이유일 수 있지만 원 글에서는 아래와 같이 Rate limit의 필요성을 설명하고 있습니다.

Rate limiting protects the APIs from accidental or malicious overuse. Without rate limiting, each user may request as often as they like, which can lead to spikes of requests that starve other consumers. After rate limiting is enabled, API calls are limited to a fixed number of requests per second.

쉽게 이아기해서 초당 요청 횟수를 제한하여 service가 예상된 요청에 대한 응답을 내려줄 수 있도록 제한하는 기능을 의미합니다.

2.4.1 Set up Rate Limiting

위 데이터 구성을 살펴보면, 분당 5회의 요청으로 제한하는 설정을 data로 주고 있습니다.

요청

curl -i -X POST http://xxx2.ap-northeast-2.elb.amazonaws.com:8001/plugins \
  --data name=rate-limiting \
  --data config.minute=5 \
  --data config.policy=local

응답

{
  "name": "rate-limiting",
  "enabled": true,
  "tags": null,
  "config": {
    "redis_database": 0,
    "redis_host": null,
    "redis_port": 6379,
    "path": null,
    "redis_password": null,
    "limit_by": "consumer",
    "second": null,
    "minute": 5,
    "hour": null,
    "day": null,
    "year": null,
    "year": null,
    "policy": "local",
    "fault_tolerant": true,
    "hide_client_headers": false,
    "header_name": null,
    "redis_timeout": 2000
  },
  "consumer": null,
  "created_at": 1623727072,
  "service": null,
  "id": "a01a7967-c6aa-4168-83be-15654c333413",
  "route": null,
  "protocols": ["grpc", "grpcs", "http", "https"]
}

2.4.2 Validate Rate Limiting

분당 5회로 요청 제한이 설정되었으므로 간단하게 curl로 1분 내 5회 이상 요청을 해보도록 하겠습니다.

여기서도 등록 이후에는 Admin(8001)이 아닌 API Gateway(80/8000)로 요청을 보내야 합니다.

요청

curl -i -X GET http://xxx2.ap-northeast-2.elb.amazonaws.com:80/mock/request

응답

{
  "message": "API rate limit exceeded"
}

2.5 Improve Performance

이 장에서는 proxy caching 기능을 살펴봅니다. plugin 구성을 통해 쉽게 기능을 반영할 수 있습니다. proxy cache 기능이 무엇인지에 대해 아래와 같이 설명하고 있습니다

Kong Gateway delivers fast performance through caching. The Proxy Caching plugin provides this fast performance using a reverse proxy cache implementation. It caches response entities based on the request method, configurable response code, content type, and can cache per Consumer or per API.

쉽게 이야기하면 이전에 요청왔던 정보들을 기억하고 있다가 동일한 요청에 대해 Servce로 전달해 응답받을 필요가 없으므로 바로 사용자에게 내려주는 기능을 의미합니다.

2.5.1 Set up the Proxy Caching plugin

내용을 살펴보면 30초간 TTL 구성동안 memory에 같은 요청이라면 저장 해두고 바로 응답으로 내려주도록 설정함을 알 수 있습니다.

요청

curl -i -X POST http://a9644d2f327aa4554813ee01a9b4a1e8-1978321371.ap-northeast-2.elb.amazonaws.com:8001/plugins \
  --data name=proxy-cache \
  --data config.content_type="application/json; charset=utf-8" \
  --data config.cache_ttl=30 \
  --data config.strategy=memory

응답

{
  "name": "proxy-cache",
  "enabled": true,
  "tags": null,
  "config": {
    "content_type": ["application/json; charset=utf-8"],
    "vary_query_params": null,
    "cache_control": false,
    "request_method": ["GET", "HEAD"],
    "vary_headers": null,
    "response_code": [200, 301, 404],
    "cache_ttl": 30,
    "storage_ttl": null,
    "strategy": "memory",
    "memory": { "dictionary_name": "kong_db_cache" }
  },
  "consumer": null,
  "created_at": 1623727908,
  "service": null,
  "id": "f5e6f07b-c6ca-45e2-9f3b-02af465b7130",
  "route": null,
  "protocols": ["grpc", "grpcs", "http", "https"]
}

2.6 Secure Services

API Gateway의 기능중 중요한 역할을 하는 부분이기도 합니다. 주로 인증(Authentication) 과 관련된 기능을 의미합니다. 인증(Authentication)과 인가(Authorization)은 헷갈리지만 차이가 있는 개념입니다.

http://www.opennaru.com/opennaru-blog/jwt-json-web-token-with-microservice/

기본적으로 인증에 사용되는 방식은 아래와 같은 방법이 존재합니다.

Basic Authentication
Key Authentication
OAuth 2.0 Authentication
LDAP Authentication Advanced
OpenID Connect

API Gateway에서 인증은 성공적으로 인증되지 않은 요청에 대해서 서비스로 요청을 전달하지 않습니다.

여러 방법 중에 API Key 인증 방법을 예제로 다루고자 합니다.

2.6.1 키 플러그인 등록

key-auth의 플러그인을 등록하면, 키 사용자 등록 및 요청 처리를 별도로 해주지 않으면 아래 메시지로 요청에 대한 응답을 거부합니다.

{
  "message": "No API key found in request"
}

요청

curl -X POST http://a9644d2f327aa4554813ee01a9b4a1e8-1978321371.ap-northeast-2.elb.amazonaws.com:8001/routes/mocking/plugins \
  --data name=key-auth

응답

{"protocols":["grpc","grpcs","http","https"],"service":null,"id":"7581a3ae-7107-4361-8e32-c91f316214ff","created_at":1623806947,"route":{"id":"81580cf8-3a6c-4b37-95df-5e810f41b07e"},"enabled":true,"config":{"key_in_body":false,"anonymous":null,"key_names":["apikey"],"hide_credentials":false,"run_on_preflight":true,"key_in_header":true,"key_in_query":true},"name":"key-auth","tags":null,"consumer":null

2.6.2 키 사용자 등록

요청

curl -i -X POST http://a9644d2f327aa4554813ee01a9b4a1e8-1978321371.ap-northeast-2.elb.amazonaws.com:8001/consumers/ \
  --data username=consumer \
  --data custom_id=consumer

응답

{
  "created_at": 1623806475,
  "username": "consumer",
  "id": "48fe36d7-b463-466f-a2db-a61c5a6941b7",
  "tags": null,
  "custom_id": "consumer"
}

2.6.3 API 키 등록

위 내용을 보면 key-auth는 RESTFul resource 구조 상 consumer에 종속되어 관리되는 것을 볼 수 있습니다.

요청

curl -i -X POST http://a9644d2f327aa4554813ee01a9b4a1e8-1978321371.ap-northeast-2.elb.amazonaws.com:8001/consumers/consumer/key-auth \
  --data key=apikey

응답

{
  "created_at": 1623807181,
  "key": "apikey",
  "consumer": { "id": "48fe36d7-b463-466f-a2db-a61c5a6941b7" },
  "id": "4bd5a77c-bcd1-43d4-a738-f5aac2d348ce",
  "tags": null,
  "ttl": null
}

2.6.4 API 키 반영 테스트

구성된 API Route 하단에 아래와 같은 파라미터로 API Key를 전달할 수 있습니다.

/?apikey=apikey

키 포함되지 않은 요청

curl -i http://a9644d2f327aa4554813ee01a9b4a1e8-1978321371.ap-northeast-2.elb.amazonaws.com:80/mock

키 포함되지 않은 요청에 대한 응답

{
  "message": "No API key found in request"
}

키 포함 요청

curl -i http://a9644d2f327aa4554813ee01a9b4a1e8-1978321371.ap-northeast-2.elb.amazonaws.com:80/mock/?apikey=apikey

키 포함 요청에 대한 응답

<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8">
<TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>
The document has moved
<A HREF="https://www.google.com/?apikey=apikey">here</A>.
</BODY></HTML>

google.com으로 요청하도록 api를 지정해두었기 때문에 성공적인 응답이 내려오는 것을 알 수 있습니다.

2.7 Set Up Intelligent Load Balancing

Load Balancing은 아래의 그림과 같이 같은 요청에 대해 부하를 분산하기 위해 사용됩니다.

Load Balancing은 TCP/IP 레이어에 따라 가능한 기능들이 다른데, Kubernetes에서 Service에서 Pod로 요청을 나누는 것은 L4 로드벨런서를 사용합니다.

더 앞단에서 URL 요청에 의해 부하를 분산시킬 수 있는 Ingress라 통칭하는 것들은 L7 로드벨런서를 사용하는데, Kong Gateway는 L7 로드밸런서의 기능을 합니다.

2.7.1 로드밸런서 구성 및 테스트

위 내용을 바탕으로 아래처럼 이전에 설정해둔 route 에 대해 google.com과 naver.com 으로 로드벨런싱 하는 과정을 진행해봅니다.

로드벨런서에 대한 upstream 생성

curl -X POST http://a9644d2f327aa4554813ee01a9b4a1e8-1978321371.ap-northeast-2.elb.amazonaws.com:8001/upstreams \
  --data name=upstream

서비스에 생성한 upstream 연결

curl -X PATCH http://a9644d2f327aa4554813ee01a9b4a1e8-1978321371.ap-northeast-2.elb.amazonaws.com:8001/services/example_service \
  --data host='upstream'

로드벨런서 taget 등록

curl -X POST http://a9644d2f327aa4554813ee01a9b4a1e8-1978321371.ap-northeast-2.elb.amazonaws.com:8001/upstreams/upstream/targets \
  --data target='naver.com:80'

curl -X POST http://a9644d2f327aa4554813ee01a9b4a1e8-1978321371.ap-northeast-2.elb.amazonaws.com:8001/upstreams/upstream/targets \
  --data target='google.com:80'

로드벨런싱 테스트

curl -X GET http://a9644d2f327aa4554813ee01a9b4a1e8-1978321371.ap-northeast-2.elb.amazonaws.com::8000/mock

3. 정리

본 글을 통해 Kong Admin으로 API를 구성하고, 그와 관련된 다양한 내용들을 살펴보았습니다. 기본적으로 제공해주는 플러그인들은 일반적인 경우를 위해 고려되었기 때문에 API Gateway에 대한 일반적인 이해를 바탕으로 필요한 경우 직접 플러그인을 구성하여 시스템을 설계할 수도 있어 보입니다.

또한 Konga를 이용해 API를 구성하면 직관적으로 기능을 이해할 수 있지만, 모든 기능을 Konga를 통해 확인하기 어려운 부분이 있으므로, 실 서비스에 활용할 목적이라면 Kong Guide 문서를 모두 읽어보시길 권장드립니다.

4. 참고자료

https://github.com/pantsel/konga

https://docs.konghq.com/getting-started-guide/2.4.x/overview/

https://docs.konghq.com/getting-started-guide/2.4.x/prepare/#verify-the-kong-gateway-configuration

http://www.opennaru.com/opennaru-blog/jwt-json-web-token-with-microservice/

Kong Gateway 2. Kong on kubernetes (Kong, Konga)

Sat, 10 Jul 2021 00:00:00 +0000

Kong, Konga에 대한 설명 및 구성 과정을 설명합니다.

0. 들어가기 전에

먼저 Kong API Gateway를 도입하기 전에 istio ingress 구성이나, nginx ingress 구성이 k8s 내에 완료되어 외부 요청에 대한 처리를 할 수 있음을 가정합니다. 특히 istio ingress로 구성되어 있는 상태를 기본으로 가정합니다.

https://kubernetes.io/ko/docs/concepts/services-networking/ingress/

위 그림은 각각 ngnix igress와 istio ingress 구성을 통해 외부 요청을 처리해주는 것을 표현합니다. 이러한 ingress들은 주로 resverse proxy의 기능을 하며 인증 등의 추가적인 기능을 위해 API Gateway가 필요할 경우 ingress 단 혹은 더 앞단에 이를 대체하는 API Gateway를 두고자 하며, 이를 Kong 으로 구성하고자 합니다.

https://istio.io/v1.9/docs/examples/virtual-machines/

https://www.nginx.com/blog/wait-which-nginx-ingress-controller-kubernetes-am-i-using/

1. Kong on Kubernetes

Istio 구성을 마친 kubernetes 환경에서 kong gateway로 ingress 기능을 처리하는 구조 및 설명이 다음 글에 잘 설명되어 있습니다.

본 글에 내용중 아래 그림이 있는데 ingress의 역할을 하게 될 Kong API Gateway가 앞에서 요청을 받아주고, K8S 내의 서비스들로 Upstream 요청을 전달하게 될 것입니다.

Isito 구성 과정에서 virtual service manifest 변경을 통해 routing을 설정하고 각 서비스로 요청을 전달했는데, Kong API Gateway로 구성하게 되면 직접 route 주소에 대해 service를 연결시킬 수 있습니다.

또한 Konga라는 front web page를 통해 Kong Admin의 설정을 쉽게 변경할 수 있는데, 그 과정도 다루어 보도록 하겠습니다.

아래 설치 환경은 ****Kubernetes 내 에서 진행됨을 말씀드립니다.

2. Kong

2.1 Kong

링크 에서 kong에 대해 자세히 설명하고 있으며 API Gateway의 구현체입니다. 설명에 따르면 nginx 기반 lua plugin들로 그 기능들을 수행한다고 합니다. Kong API Gateway는 Enterprise 버전과, OSS(Open Source) 버전을 모두 제공하고 있습니다.

Kong can help by acting as a gateway (or a sidecar) for microservices requests while providing load balancing, logging, authentication, rate-limiting, transformations, and more through plugins.

설명에 따르면, load balancing, 로깅, 인증 등 API Gateway가 가져야할 기능들을 다양한 플러그인을 통해 제공할 수 있다고 합니다.

2.2 Kong 설치

기본적으로 공식 helm chart로 kong을 설치하게 되면 아래와 같은 방식으로 설치하도록 가이드하고 있습니다.

$ helm repo add kong https://charts.konghq.com
$ helm repo update

# Helm 2
$ helm install kong/kong

# Helm 3
$ helm install kong/kong --generate-name --set ingressController.installCRDs=false

https://github.com/Kong/charts

하지만 위 설정대로 진행하면 kong은 dbless 방식으로 뜨게 되고, 나중에 konga 툴로 service 나 route 등을 등록할 수 없게 됩니다. 따라서 링크에서 구성된 kong chart는 default로 postgres db가 K8S 내에서 kong과 같이 뜨도록 구성되어 있습니다.

물론 kong 공식 charts에서 yaml manifest를 변경함으로 db 구성을 지정할 수 있지만, 효율적인 과정을 위해 아래 내용으로 진행하도록 합니다.

kong 설치 진행 (with posgres)

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

helm install kong \
--set service.exposeAdmin=true \
--set ingressController.installCRDs=false \
--set namespace=kong \
bitnami/kong

링크에서 살펴보면, 여러가지 옵션을 변경할 수 있도록 문서화가 잘 되어있습니다.

기본적으로 bitnami의 helm chart는 postrgres가 default로 설정되어 있기 때문에 위 구성대로 kong을 설치하게 되면 postgres db가 함께 뜨고, kong admin의 port는 expose 됩니다.

3. Konga

3.1 Konga

링크에서 konga에 대한 설명을 확인하실 수 있습니다. 기본적으로 kong은 API들을 구성할때 kong admin 주소로 rest 요청을 통해 설정합니다. 번거로운 작업이 될 수 있고 익숙하지 않은 사람에겐 불편한 작업이 됩니다.

kong enterprise 버전에서는 admin page를 제공하는 것 같은데, open source 버전도 konga를 이용해 admin 페이지를 구성할 수 있습니다.

Manage all Kong Admin API Objects.

Import Consumers from remote sources (Databases, files, APIs etc.).

Manage multiple Kong Nodes.

Backup, restore and migrate Kong Nodes using Snapshots.

Monitor Node and API states using health checks.

Email & Slack notifications.

Multiple users.

Easy database integration (MySQL, postgresSQL, MongoDB).

3.2 konga 설치

konga를 활용해서 다양한 설정을 적용하려면, Kong이 db와 함께 구성되어 있어야 합니다. dbless로 구성될 경우 API 설정들의 조회는 가능하나, 추가/수정은 불가능합니다. 앞서 소개해드린 bitnami helm chart로 구성하면 자동으로 postgres db가 함께 구성되는데, 실제 서비스에 적용할 때는 안정적으로 구성된 db를 연동하는 것이 필요해 보입니다.

konga 설치 진행

konga helm chart 주소에 있는 내용을 바탕으로 설치하고 repository에 있는 helm chart를 직접 설치합니다.

https://github.com/pantsel/konga

git clone https://github.com/pantsel/konga.git
cd konga/charts
helm install konga konga/

4. Kong, Konaga 연동

kubectl get service 명령으로 아래와 같이 설치된 것을 확인하실 수 있습니다.

여기서 저는 외부 접속을 허용하기 위해 kong, konga를 LoadBalancer Type 으로 변경했습니다.

본 글에서 nlb 주소를 변경하였지만, 표시된 xxx.ap-northeast-2.elb.amazonaws.com 주소로 접속하시면 계정 생성 후 아래 화면을 보실 수 있습니다.

NAME                       TYPE           CLUSTER-IP       EXTERNAL-IP                                                                    PORT(S)                                                    AGE
kong                       LoadBalancer   172.20.249.30    xxx.ap-northeast-2.elb.amazonaws.com    80:32388/TCP,443:31964/TCP,8001:31018/TCP,8444:31915/TCP   17d
kong-metrics               ClusterIP      172.20.80.144    <none>                                                                         9119/TCP                                                   17d
kong-postgresql            ClusterIP      172.20.252.142   <none>                                                                         5432/TCP                                                   17d
kong-postgresql-headless   ClusterIP      None             <none>                                                                         5432/TCP                                                   17d
konga                      LoadBalancer   172.20.126.171   xxx.ap-northeast-2.elb.amazonaws.com   80:31741/TCP                                               17d

APPLICATION-CONNECTIONS 페이지에서 위와 같이 kong admin 주소를 연결해주면 Kong API Gateway의 설정된 정보들을 읽을 수 있습니다.

NLB로 public url 주소가 있는 경우 그 주소를 입력해도 되고, 같은 네트웍 상에서 구성되었다면 위와 같이 service 명으로도 연동 가능합니다.

6. API 설정 테스트

먼저 Kong API Gateway의 구성은 위 그림을 통해 보면 자세히 알 수 있습니다.

간단한 API 들의 연동을 테스트 해보려고 하는데, 최소한으로 Service → Route 를 설정해야 합니다.

뒤 내용에서 살펴보겠지만 Route는 Service에 종속되고, Consumer는 Route에 종속되는 형태로 구성됩니다.

Konga를 설치하지 않았다면 REST 기반의 Admin API 로 구성하는 방법이 있습니다.

Konga를 통해 위와 같은 구성의 포털로 호출하는 API를 설정하는 것을 살펴보도록 하겠습니다.

6.1 Service 구성

왼쪽 탭의 Services에서 ADD NEW SERVICE를 누르면 위 화면을 볼 수 있습니다.

Url을 위와 같이 구성해주면, Host, Port, Path 등이 자동으로 들어가게 됩니다.

생성된 google service를 선택하면 필요한 내용들이 자동으로 들어가있는 것을 볼 수 있고, 왼쪽 탭에 Routes와Plugins을 통해 Service에 Routes와 Plugins이 종속되어 있음을 확인할 수 있습니다.

6.2 Route 구성

이제 사용자가 호출할 때 http://{kong address}/{route} 로 요청할 수 있도록 Routes를 구성해야 하는데, 왼쪽 탭의 Routes를 누르면 사진처럼 YOU CAN ONLY CREATE ROUTES FROM A SERVICE PAGE라는 링크를 볼 수 있습니다.

누르면 결국 6.1에서 봤던 서비스 화면으로 이동하게 됩니다.

여러 설정을 구성할 수 있지만 테스트를 위해 붉게 표시된 부분들만 구성해주도록 합니다.

Paths와 Meethods는 반드시 엔터 를 눌러서 회색 모양으로 만들어주셔야 합니다.

그렇지 않으면 설정이 저장되지 않습니다.

6.3 Consumer 구성

6장 도입부 그림을 보면 consumer 구성을 볼 수 있는데, 인증 등의 처리를 위해 consumer를 구성할 수 있습니다. (특정 사람만 google로 요청할 수 있도록 인증/인가)

하지만 이 글에선 기본적인 API 설정에 대해서만 다루는 것이 목표이기 때문에 본 글에서 consumer는 다루지 않도록 하며 기회가 되면 다른 chapter에서 다루어 보도록 하겠습니다.

6.4 테스트

curl -X GET {kong nlb address}/google
curl -X GET {kong nlb address}/naver
curl -X GET {kong nlb address}/kakao

7. 정리

위 과정은 kong, konga 모두를 연동하고 다양한 실험을 진행한 후에 정리한 글입니다.

여러 글을 참고하여 구성했으나, db없이 구성했다가 다시 삭제하고 등의 시행착오를 겪었습니다. 별 내용은 없고 helm chart에 대한 자세한 설명을 섞진 않았으나 실험을 진행하기에 알맞게 잘 구성된 helm chart와 과정을 소개하는 것과 직접 시도해보지 않고 해당 과정으로 어떤 식으로 진행되는 지를 공유드리는 것이 목적임을 밝힙니다.

6. 참고자료

https://kubernetes.io/ko/docs/concepts/services-networking/ingress/

https://istio.io/v1.9/docs/examples/virtual-machines/

https://www.nginx.com/blog/wait-which-nginx-ingress-controller-kubernetes-am-i-using/

https://github.com/Kong/charts

https://github.com/pantsel/konga

Kong Gateway 1. API Gateway, Reverse Proxy, Ingress

Sat, 10 Jul 2021 00:00:00 +0000

API Gateway, Reverse Proxy, Ingress 에 대해 설명합니다.

0. 들어가기 전에

Kuberentes 기반 MSA 서비스를 구성함에 있어 Gateway와 Ingress 부분을 어떻게 구성할지 고민이 필요했습니다. 그 과정에서 Kong Gateway가 대안으로 고려되었는데, 그 전에 API Gateway, Reverse Proxy, Ingress 등의 기본적인 개념을 정리하고 넘어가기 위해 글을 정리합니다.

1. API Gateway, Reverse Proxy, Ingress

헷갈리는 개념은 명확하게 짚고 넘어가야 나중에 문제가 발생하지 않으므로, 이미 알고있는 내용이라도 공신력(?) 있는 정보를 바탕으로 정확하게 짚어보도록 하겠습니다.

간단하게는 세 개념 모두 외부의 요청을 받아 내부의 서비스를 처리하는 기능을 합니다.

1. API Gateway

먼저 wiki에 관련된 내용을 참고해봅니다.

아래 내용을 보면 API Gateway의 기능 중 일부를 자세히 설명하고 있습니다.

API frontend 역할을 하고, API 요청을 수신하고, 제한 및 보안 정책을 시행하고, 요청을 백엔드 서비스에 전달한 다음, 요청자에게 다시 응답을 전달하는 서버입니다. 게이트웨이에는 요청과 응답을 직접 조정 하고 수정 하는 변환 엔진이 포함되는 경우가 많습니다. 게이트웨이는 분석 데이터 수집 및 캐싱 제공과 같은 기능도 제공할 수 있습니다. 게이트웨이는 인증, 권한 부여, 보안, 감사 및 규정 준수를 지원하는 기능을 제공할 수 있습니다. 게이트웨이에는 요청과 응답을 직접 조정 하고 수정 하는 변환 엔진이 포함되는 경우가 많습니다. 리버스 프록시로 구현할 수 있습니다.

이런 기능을 하는 API Gateway는 AWS 나 GCP 등의 public cloud에서 console로 쉽게 구성하도록 제공하기도 하며, 서두에 언급한 Kong API Gateway 와 같이 open source로 구성된 프로젝트도 있습니다.

2. Reverse Proxy

마찬가지로 wiki에 관련된 내용을 참고해봅니다.

아래 내용은 Reverse Proxy의 기능 중 일부를 설명하고 있는데 표현이 다르지만 사실 API Gateway에서 표현된 내용과 일치하는 부분들이 있습니다.

역방향 프록시를 다른 기술과 함께 사용하여 내부 서버 간의 로드 균형 을 조정 합니다. 역방향 프록시는 정적 콘텐츠 캐시를 유지할 수 있으므로 이러한 내부 서버와 내부 네트워크의 부하를 더욱 줄일 수 있습니다. 역방향 프록시가 클라이언트와 역방향 프록시 간의 통신 채널에 압축 또는 TLS 암호화 와 같은 기능을 추가하는 것도 일반적입니다.

리버스 프록시 서버는 Apache , Nginx 및 Caddy 와 같은 널리 사용되는 오픈 소스 웹 서버 에서 구현됩니다.

3. Ingress

이번엔 kubernetes에서 자주 언급되는 용어인 Ingress에 대한 내용을 살펴봅니다.

클러스터 내의 서비스에 대한 외부 접근을 관리하는 API 오브젝트이며, 일반적으로 HTTP를 관리함. 인그레스는 부하 분산, SSL 종료, 명칭 기반의 가상 호스팅을 제공할 수 있다.

Ingress 역할을 하기 위해 nginx ingress, istio ingress 등의 구성으로 외부 요청을 내부로 전달하는 목적의 기능을 수행합니다.

kubernetes의 Ingress의 개념은 결국 API Gateway와 Reverse Proxy의 개념과 맞닿아 있습니다. 외부 요청을 받아 내부의 서비스로 전달하는 과정을 어떻게 구성할지 고민이 필요합니다.

2. 정리

위 내용들을 살펴보면 외부 요청을 받아 내부의 서비스로 전달하는 목적에 대해 유사한 기능들을 설명하고 있습니다. 실제로 API Gateway가 Proxy보다 더 상위 개념이라고 볼 수 있습니다.

간단한 서버 구성의 경우 외부의 호출을 처리하기 위해 nginx proxy 서버로 처리 가능합니다.

다만, 서비스 영역이 커지면서 외부의 요청을 제한하거나 처리하기 위한 인증 등의 처리가 필요할 경우 앞단에 API Gateway로 통합된 기능을 처리하게 됩니다.

실제로 앞서 언급된 Kong API Gateway는 개발 기반 자체가 nginx 위에서 lua로 개발된 plugin들의 구성으로 되어있다고 합니다.

akana 에서 작성한 글에 적당한 그림이 있어 첨부하여 이 글을 마무리하고자 합니다.

3. 참고자료

https://en.wikipedia.org/wiki/API_management

https://en.wikipedia.org/wiki/Reverse_proxy

https://kubernetes.io/ko/docs/concepts/services-networking/ingress/

https://www.akana.com/blog/api-proxy-vs-api-gateway

Python - WSGI 와 Flask 연동에 대한 필요성

Sat, 15 May 2021 00:00:00 +0000

본 글은 python 기반 Flask로 서버를 구성함에 있어 WSGI 와의 연동에 대한 필요성을 설명합니다.

0. 들어가기 전에

요즘 Tensorflow와 Torch 기반으로 모델 개발을 하시는 분들이 많은데 구축한 모델을 추론하는 서버를 서비스에 적용하거나 테스트할 목적으로 flask로 구성하는 경우가 많을 것입니다.

물론 TensorFlow serving 과 Torch Serve에 대해서 다루는 글은 아니며, 딥러닝과 전혀 관계 없이 API 서버를 구성함에 있어 가벼움의 장점을 갖는 Flask로 많이 구성하시게 될 것입니다.

python 기반의 프레임워크로 서버를 구성할 때 고민해야 할 포인트들이 많습니다. 그냥 python이 친숙하거나 쉽다고 Flask로 서버를 구성하여 실제 서비스 제공할 생각이라면 위험 할 수 있다고 생각합니다.

그래서 두루뭉술한 개념들을 정리하고 고민해볼 포인트와 실험 해볼 포인트들을 정리하여 기술해보고자 합니다.

1. 서버 구성 비교 (Web Server + CGI + Application, Web Application Server)

본 글은 Web Server와 Web Application Server간의 차이 등을 다루고 자하는 글이 아니지만, 필요한 내용이 있어 간단한 그림을 준비했습니다. 더 자세한 구조 혹은 WAS, WebServer, CGI 등에 대해 잘 모르신다면 깊게 다룬 관련 글들이 많으므로 찾아보시길 권해드립니다. 두가지만 짧게 짚고 넘어가겠습니다.

1.1. 정적 웹서버 vs 동적 웹서버

정적 웹서버 : 정적 웹 서버 혹은 스택은 HTTP 서버 (소프트웨어)가 있는 컴퓨터(하드웨어)로 구성되어 있습니다. 서버가 그 불려진 파일을 당신의 브라우저에게 전송하기 때문에 그것을 “정적”이라고 부릅니다.

동적 웹서버 : 동적 웹 서버는 정적 웹 서버와 추가적인 소프트웨어(대부분 일반적인 애플리케이션 서버와 데이터베이스)로 구성되어 있습니다. 애플리케이션 서버가 HTTP 서버를 통해 당신의 브라우저에게 불려진 파일들을 전송하기 전에, 애플리케이션 서버가 업데이트하기 때문에 이것을 동적이라고 부릅니다.

mozilla

다시 말해서 html, javascript 만을 제공하는 정적 웹서버를 구성하고 싶다면 Flask로 띄울 필요가 없다는 이야기 입니다.

만약 db 연동이나 로직을 처리하는 application을 구성해야 하는 경우라면 그때 flask나 django가 필요하다는 이야기 입니다.

1.2. CGI/WSGI는 왜 필요한가?

CGI와 관련된 자세한 내용을 원하신다면 참고글을 한번 읽어보시길 권해드립니다. 여기서는 이해를 돕기 위해 쉽게 설명하고 넘어가도록 하겠습니다.

공용 게이트웨이 인터페이스(영어: Common Gateway Interface; CGI)는 웹 서버 상에서 사용자 프로그램을 동작시키기 위한 조합입니다.

Wiki에 정리된 말 그대로 C로 만들어진 Ngnix Webserver 에서 다른 언어로 만들어진 application을 호출하고 그 결과를 사용자에게 전달하려면 중간에서의 처리를 담당하는 것이 필요하다고 생각 될 것 같습니다.

CGI를 사용하는 경우 : 클라이언트 -> 웹서버 -> CGI -> Application
WSGI를 사용하는 경우 : 클라이언트 -> 웹서버 -> WSGI (미들웨어) -> Application Server

WSGI는 Application Server를 연결해주는 미들웨어로서의 역할을 수행하며 그와 관련된 Python 계열의 WSGI는 gunicorn, uWSGI 등이 있으며 공식 문서를 보면 worker 기반으로 배포 시 서버를 효과적으로 구성할 수 있는 많은 옵션들을 제공해줍니다.

1.3. Flask/django 만 사용 한다는 것은?

flask/django만 이용해서 서버를 구성한다는 것은 사용자가 직접 Application Server로 호출 하게 한다는 의미라고 볼 수 있습니다.

물론 flask가 정적 웹 서버를 제공하도록 만들 수도 있으니 그냥 저렇게 호출하면 안되냐고 생각하실 수 있는데, Web Server가 해주는 기능이 단순히 정적 웹 페이지를 내려주는 것만 하는 것이 아닙니다.

nginx 기능을 보시면 로드 벨런싱부터 다른 많은 기능을 제공해 주고 있습니다. Flask만으로는 본래 웹서버가 처리해줘야 할 많은 기능들을 처리하기 어렵다는 이야기 입니다.

2. Flask는?

Flask는 python 기반 웹 애플리케이션 프레임워크이며 django와 달리 db와 같은 기능들을 자체 프레임워크에 포함하고 있지 않기 때문에 가볍습니다. 따라서 작은 프로젝트에서 부터 확장성이 필요한 여러 프로젝트까지 다양한 목적으로 많이 사용됩니다.

개발 단계에서 Flask로 간단한 빌트인 서버를 띄울 수 있는데 실제 서비스 목적으로 배포해야 한다면 Flask 공식 글에서 WSGI를 붙여야 한다고 권장하고 있습니다.

This launches a very simple builtin server, which is good enough for testing but probably not what you want to use in production. For deployment options see Deployment Options. Flask’s built-in server is not suitable for production as it doesn’t scale well

flask app은 기본적으로 blocking 작업이 있을때 동기적으로 방식으로 동작하기 때문에 여러 요청이 있을 경우 순차적으로 응답합니다. File IO, 외부 API 호출, 딥러닝 모델 추론 등의 긴 연산 시간이 필요할 경우 WSGI와의 연동이 필요합니다.

3. WSGI는?

1번 항목에서 WSGI에 대한 언급을 조금 하긴 했는데, 이번 글에서는 대표적으로 많이 쓰이는 WSGI 중 uWSGI를 예를 들어서 정리해보도록 하겠습니다.

uWSGI는 Nginx(Web Server)와 Flask를 연결해주는 인터페이스 역할 뿐만 아니라, 많은 기능을 제공하고 있습니다. 다른 WSGI들도 비슷한 기능들을 제공해주겠지만 각각의 비교는 이 글에

서 다루지 않습니다.

이 기능들 중에 Flask가진 단점 중 순차적 응답에 대한 문제를 multi process, thread 기반의 worker 방식으로 해결할 수 있습니다. 서버 구성 방식도 여러가지가 존재합니다.

또한 Flask 서버에서 memory leak이 발생했을때 일정 메모리 이상 올라갈 경우 worker 를 재시작 하는 등의 옵션도 제공합니다. 이 문제와 관련해서는 인스타그램 의 사례를 보면 이해가 됩니다.

uWSGI와 Flask를 연동하여 서버를 구성하면 목적에 맞게 다양한 방식을 구성할 수 있습니다.

prefork, lazyapp, emperor mode, zerg dance 등 시간이 되시면 uWSGI 서버 배포 모드 글을 읽어보시면 각 모드에 대해 그림으로 이해하기 쉽게 설명해 놓았습니다.

지금까지의 내용을 단순한 그림으로 정리하고 넘어가겠습니다.

파란색 네모를 시간이 오래걸리는 요청이라고 생각하면 Flask로 직접 요청하는 것과 WSGI를 통해서 요청하는 것의 차이는 위의 모습으로 쉽게 이해할 수 있습니다. 물론 DB Connection이나 큰 딥러닝 모델을 물고 worker를 구성할 것인지 등의 구조는 서버 배포 모드 방식과 Application 코드 구성과 맞물려 있습니다.

그림을 통해 보면 당연히 WSGI를 통해 요청하게 되면 시간이 많이 걸리는 요청에 대해 많은 사용자 트래픽을 효율적으로 처리할 수 있다는 것을 이해할 수 있습니다.

4. 정리

가벼운 마음으로 글을 작성하기 시작했는데 생각보다 하고싶은 말을 바로 적으려니 읽으시는 분의 배경 지식에 따라서 제 생각이 잘 전달되지 않을 것 같다고 생각했습니다. 원래는 flask에 대한 동시성 성능에 대한 테스트를 주로 다루려고 시작했던 글인데 관련된 개념 부터 정리하게 되었습니다. 이후 WSGI와 연관되는 내용들을 정리하고 공유드릴 수 있는 기회가 있으면 좋겠습니다.

참고자료

https://developer.mozilla.org/ko/docs/Learn/Common_questions/What_is_a_web_server

https://flask.palletsprojects.com/en/1.1.x/quickstart/#a-minimal-application

https://docs.python.org/3.0/howto/webservers.html

http://zarnovican.github.io/2016/02/15/uwsgi-graceful-reload/

Golang Testing - 2. HTTP Request Mocking

Sat, 15 May 2021 00:00:00 +0000

본 글은 golang으로 Testcase를 구성할 때 http request를 실제 서버로 보내지 않고, http request와 관련된 mock을 구현하는 방법에 대해서 설명합니다.

0. 시작하기 전에

golang으로 api 서버를 만들다보면 3rd api와 연동해야 하는 일이나 MSA 구조라면 간단한 비즈니스 로직을 처리하기 위해서 다른 서비스로 요청해야 하는 경우가 많을 것 입니다. 이런 상황에서 외부 연동에 대한 코드는 무시하고 fucntional한 unit 테스트만 진행하다 보면 이전 글에서 언급되었던 cover 등으로 확인해봤을때 실제로 많은 영역의 코드를 테스트 할 수 없고 이는 리스크로 남게됩니다.

물론 실제 서버로 직접 요청하는 것을 포함한 unit 테스트를 구성해도 좋지만 만약 다음의 경우라면 문제가 될 가능성이 있습니다.

목적지 서버가 k8s 같은 클러스터 내부에 있어 외부에서 직접 호출할 수 없다. (배포 후에나 요청 가능하다)
목적지 서버가 먼저 떠있어야 로직상 테스트를 돌릴 수 있기에 배포 순서를 지켜야 한다.
단순히 자체 코드에 대한 영향성 만을 보고싶은데 목적지 서버에 종속성이 생긴다.
실제 서버로 요청해버리면 응답 속도가 너무 늦어 테스트나 배포 시간이 오래 걸린다.

이러한 불편한 상황을 막기 위해 local에서 기대되는 요청에 대한 응답을 mocking 하여 실제 서버에는 요청하지 않지만 마치 요청에 대한 응답을 받은 것 같은 기대효과를 얻을 수 있습니다.

1. 예제 시나리오

예를 들면 아래 그림처럼 productpage 서버를 구현한다고 가정해봅시다. 그러면 details 서버와 review 서버로 요청을 보낸 뒤 사용자에게 응답을 내려주는 기능을 구현해야 합니다.

그리고 details 서버와 reviews 서버는 외부에서 호출이 불가능하도록 구현이 되어있고, 배포 후에 해당 망 안에서 호출할 수 있는 경우라고 가정해봅니다.

이런 경우엔 실제 서버로 요청을 보내는 기능을 포함해서 테스트케이스를 구성할 수 없습니다. 이런 문제 상황을 극복하기 위해 HTTP Request를 mocking 하는 방법에 대해 기술하고자 합니다.

https://raw.githubusercontent.com/kiali/kiali.io/master/static/images/documentation/features/graph-overview.png

2. Interface 에 대한 이해

먼저 본 과정을 이해하시려면 interface를 이해하셔야 합니다. 다른 java나 c++ 같은 객체 지향 언어를 공부하신 분들이라면 잘 알고계실 다형성과 관련된 이야기 입니다. 쉽게 이야기하실 수 있도록 그림을 하나 두고 이야기해보겠습니다. 혹시라도 제대로 interface에 대해 공부하시고 넘어가고 싶으시다면, 관련해서 깊게 다룬 글들을 쉽게 검색해서 찾아보실 수 있으므로 잠깐 이 글 읽는 것을 멈춘뒤 이해하고 나서 진행하시는 것도 좋습니다.

그림 출처 : https://docsplayer.org/77693386-Powerpoint-프레젠테이션.html

사실 이 글에서 다루려고 하는건 복잡한 내용이 아니라 http clinet의 mocking과 관련된 부분만 언급하려고 합니다.

그림으로 보시면 유명하고 뻔한 짖다 모델을 가져왔습니다. “짖다” 의 동작을 “누가” 하는지에 따라 다르게 처리한다. 이 정도 개념으로만 이해하시면 충분할 것 같습니다.

“짖다 - httpRequset” 라는 동작을

본 코드(강아지) 가 하면 “멍멍”

테스트 코드(고양이) 가 하면 “야옹”

과 같은 느낌이 되겠네요.

golang에서도 이러한 구현을 위해 interface 기능을 제공합니다.

3. 테스트 구성

3.1. 예제 시나리오

이번 예제에서도 자주 쓰는 google, naver, kakao로 http 요청을 하는 정말 간단한 코드를 두고 테스트케이스를 구성해보도록 하고, 구현 먼저 하고 테스트코드를 작성하는 순서로 진행하겠습니다.

또한 golang 기본 tool 로 제공하는 cover 사용 및 testcase 구성 방법 등은 Golang Testing - Unit Test 구성하기를 참고하시면 도움됩니다.

3.2. 직접 호출 기반 UnitTest 구성

main.go

package main

import (
	"fmt"
	"io"
	"net/http"
)

func requestPortal (metod, url string) (*string, error) {

	req, err := http.NewRequest(metod, url, nil)
	if err != nil {
		return nil, err
	}

	cli := &http.Client{}
	resp, err := cli.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	// golang 1.16 부터 io.ReadAll 사용 가능
	b, _ := io.ReadAll(resp.Body)
	result := string(b)

	return &result, nil
}

func main() {
	urlList := []string{"https://google.com", "https://naver.com", "https://daum.net", "https://myportal.my"}
	for _, url := range urlList {
		res, err := requestPortal (http.MethodGet, url)
		if err != nil {
			fmt.Println(err)
		} else {
			fmt.Println(*res)
		}
	}
}

main_test.go

package main

import (
	"fmt"
	"net/http"
	"strings"
	"testing"
)

func Test_requestPortal (t *testing.T) {

	expectedResult := "google"
	type args struct {
		metod string
		url   string
	}
	tests := []struct {
		name    string
		args    args
		want    *string
		wantErr bool
	}{
		{
			name: " TC1. 포털 사이트 요청 테스트",
			args: args{
				metod: http.MethodGet,
				url:   "https://gogole.coom",
			},
			want:    &expectedResult,
			wantErr: false,
		},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			got, err := requestPortal (tt.args.metod, tt.args.url)
			fmt.Println(err)
			if err == nil {
				if !strings.Contains(*got, *tt.want) {
					t.Errorf("requestPortal () = %v, want %v", got, tt.want)
				}
			}
		})
	}
}

테스트 결과

$go test -coverprofile=cover.out
coverage: 52.9% of statements
ok      test    0.593s
$go tool cover -html=cover.out

3.3 과정에서는 직접 목적지 서버에 요청을 하는 과정을 unit 테스트로 구성하였고, 그 결과 main 함수 외에 대부분의 statement가 커버됨을 확인할 수 있습니다.

3.4. 문제 발생 케이스

만약 google.com이 아니라… 예제에서 들었던 것 처럼 현재 테스트 수행 환경에서는 호출 불가능한 목적지 서버로 호출해야 하는 경우가 있다면 어떨까요.

그러니까 internal 환경으로 배포하고 나면 코드상에 구현되어 있는 url로 정상 동작하지만 배포 전 내 컴퓨터에서 닿지 않는 곳의 목적지 서버로 요청을 보내야 하는 경우에는 테스트를 어떻게 해야할까요.

확인을 위해 gogole.coom 이라는 존재하지 않는 페이지로 요청을 보내는 테스트케이스를 구성해 보겠습니다.

테스트 결과

$go test -coverprofile=cover.out
Get "https://gogole.coom": dial tcp: lookup gogole.coom: no such host
PASS
coverage: 35.3% of statements
ok      test    0.014s
$go tool cover -html=cover.out

coverage 수치로도 확실히 줄었고, cover 툴을 이용해서 확인해봐도 존재하지 않는 host로의 요청에 의해 응답이후를 처리하는 부분들이 커버되지 않았습니다.

뿐만 아니라 이 테스트코드를 가진 상태로 Makefile 등을 구성하면 testcase가 Fail이 나기 때문에 배포 환경에 따라 문제가 발생할 수 있습니다.

3.5. Mock Client 구성

이제 Mock client를 구성할 차레입니다. 앞 단계에서 쉬운 예로 들었던 내용처럼

“짖다(Do)” 의 기능을

“main.go”에서 하면 “http.client{} 로 구현된 Do 수행” - 강아지

“main_test.go”에서 하면 “MockClient{} 로 새롭게 구현된 Do 수행” - 고양이

하도록 구성할 것 입니다.

이를 위해 Do를 담을 HTTPClient 라는 이름의 interface를 선언하고, 실제 동작할 함수의 구현은 리시버에 그 handler 타입을 받아 구현합니다.

main.go

package main

import (
	"fmt"
	"io"
	"net/http"
)

// HTTPClient interface
type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

type Handler struct {
	cli HTTPClient
}


func NewRequestHandler() *Handler {
	return &Handler{
		cli: &http.Client{},
	}
}

func (h Handler) requestPortal (metod, url string) (*string, error) {

	req, err := http.NewRequest(metod, url, nil)
	if err != nil {
		return nil, err
	}

	// 이 부분을 interface로 정의된 HTTPClient type, &http.clinet{} 값을 갖는 값으로 지정한다.
	// 이렇게 되면 Do(req *http.Request) (*http.Response, error) 의 기능은 원래 존재하는 http client의 Do 함수를 사용한다.
	// 실제 코드를 이렇게 구성하면 의도한대로 동작한다.
	cli := h.cli
	resp, err := cli.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	// golang 1.16 부터 io.ReadAll 사용 가능
	b, _ := io.ReadAll(resp.Body)
	result := string(b)

	return &result, nil
}

func main() {
	urlList := []string{"https://google.com", "https://naver.com", "https://daum.net", "https://myportal.my"}
	for _, url := range urlList {

		//이 부분도 handler를 통해 호출하는 방식으로 변경해준다.
		res, err := NewRequestHandler().requestPortal (http.MethodGet, url)
		if err != nil {
			fmt.Println(err)
		} else {
			fmt.Println(*res)
		}
	}
}

main_test.go

package main

import (
	"bytes"
	"io"
	"net/http"
	"testing"
)

// MockClient is the mock client
type MockClient struct {
}

// Do 를 재구현 함으로써 MockClient 어댑터로 구현된 기능은 본래의 Do와 다르게 동작한다.
func (m *MockClient) Do(req *http.Request) (*http.Response, error) {
	json := `{ "description": "okay" }`
	r := io.NopCloser(bytes.NewReader([]byte(json)))
	defer r.Close()

	return &http.Response{
		Status:     "200 Ok",
		StatusCode: http.StatusOK,
		Body:       r,
	}, nil
}

func TestHandler_requestPortal (t *testing.T) {

	h := NewRequestHandler()
	// MockClient로 cli를 변경해주면서 MockClient 어댑터로 새로 구현된 Do가 호출된다.
	h.cli = &MockClient{}

	expectedResult := `{ "description": "okay" }`
	type fields struct {
		cli HTTPClient
	}
	type args struct {
		metod string
		url   string
	}
	tests := []struct {
		name    string
		fields  fields
		args    args
		want    *string
		wantErr bool
	}{
		{
			name: " TC1. 포털 사이트 요청 테스트",
			args: args{
				metod: http.MethodGet,
				url:   "https://gogole.coom",
			},
			want:    &expectedResult,
			wantErr: false,
		},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			got, err := h.requestPortal (tt.args.metod, tt.args.url)
			if (err != nil) != tt.wantErr {
				t.Errorf("requestPortal () error = %v, wantErr %v", err, tt.wantErr)
				return
			}
			if *got != *tt.want {
				t.Errorf("requestPortal () = %v, want %v", got, tt.want)
			}
		})
	}
}

테스트 결과

$go test -coverprofile=cover.out
PASS
coverage: 55.6% of statements
ok      test    0.009s
$go tool cover -html=cover.out

호출할 수 없는 url로 구성한 unit 테스트 구성으로도 코드의 syntax 나 panic을 확인해 볼 수 있는 converage 를 확보할 수 있는 것을 알 수 있습니다.

4. 정리

테스트의 중요성은 실제로 문제를 겪어보면 절실히 깨닫게 되는 것 같습니다. 소잃고 외양간 고치는 느낌처럼 문제가 발생한 뒤에 해결하려고 한다면 이미 입은 피해는 되돌릴 수 없다는 것도 잘 알게됩니다.

테스트 구성은 안했지만 자주 호출되는 부분들은 몇번 테스트 해봤는데 잘 동작하니까 그대로 배포해버리고 잊어버리고 살고 있다면, 갑자기 발생한 critical 한 이슈를 개선하려고 기억도 잘 나지 않는 코드에서 헤메게 될 가능성이 있습니다.

갑자기 발생한 코너케이스나 엣지케이스로 panic이 발생하고, 이를 복구할 수 있는 최소한의 recover나 error handling이 안되어 있다면 복구하는데 드는 리소스 뿐만 아니라 비즈니스에도 큰 영향을 주게 됩니다.

따라서 Test driven 설계를 하거나, 설계 이후에 Test code를 구성하거나 하는 작업은 무시되어선 안된다고 생각합니다. 사실 Testcase를 구성하는 과정에서 coverage를 함께 보다 보면 놓쳤던 부분들이 하나씩 볼 수 있는 경험을 하게되는 것 같습니다.

참고자료

https://www.thegreatcodeadventure.com/mocking-http-requests-in-golang/

https://quii.gitbook.io/learn-go-with-tests/go-fundamentals/mocking

https://levelup.gitconnected.com/mocking-outbound-http-calls-in-golang-9e5a044c2555

Golang Testing - 1. Unit Test 구성하기

Sun, 09 May 2021 00:00:00 +0000

본 글은 Golang으로 개발함에 있어 Testing 패키지를 활용해 Test를 구성/수행 및 Coverage와 Benchmark를 확인할 수 있는 방법에 대해 설명합니다.

0. 시작하기 전에

golang으로 개발을 진행하면서 많은 api 서버를 구성했습니다. 개발 기간의 부족, 테스트에 대한 범위의 모호 등 합리적이지 않은 합리화로 unit 테스트 코드를 작성하는데 소흘했던 것 같습니다.

혹시나 누군가는 테스트 코드를 작성하고는 싶은데, 어떻게? 어디까지? 등에 대해서 궁금증을 갖고 계신분이 있을 수 있어 테스트와 관련해서 조금씩 덧붙여 작성해보려고 합니다.

이번 글에서는 TDD 같은 개발 방법론에 대한 이야기를 하지 않고 단순하게 테스트 코드를 만드는 과정에 대해서만 언급하려고 합니다.

0.1. 개발 환경 (갑자기..?)

저는 평소 개발할때 다양한 언어를 사용하거나 인프라 코드들을 편집합니다. python, golang, java, javascript, html, shell, json, yaml… 한동안 JetBrains 사의 Professional 도구들을 사용하곤 했는데, 언어마다 다른 도구로 존재해서 그 마다 전문성이 느껴지고 좋은 기능들이 너무 많지만 단축키나 환경 설정들이 각 툴마다 조금씩 다른 것에 대한 아쉬움을 느꼈습니다.

그래서 저는 각 도구의 전문성을 포기하고 VS Code로 통합해서 개발해보는 방법으로 Golang 개발을 VS Code로 하고 있습니다. 편리한 플러그인들이 많은데 이 설치한 환경 자체도 github와 연동해 어디서든 동기화 시킬 수 있습니다. (VS Code 얘기는 그만….)

갑자기 뜬금없이 왜 개발환경을 이야기하냐 물어보신다면 테스트 코드를 구성하는 것은 결국 생산성에서 문제를 겪게 된다고 생각합니다. 매번 테스트 코드를 컨벤션에 따라 직접 구성하는것도 좋지만,

만약 도구에서 효율적으로 자동으로 만들어주는 부분이 있다면 적극 활용하는게 좋을 것 같다고 생각했습니다.

VS Code에 그 기능이 존재해서 소개드리고자 합니다. (JetBrains 사의 GoLand도 같은 기능을 갖고 있습니다.)

1. 테스트 코드 만들기

1.1. 직접 만들기

golang.org의 testing package 내용은 시간이 허락한다면 꼭 한번 읽어보시기 바랍니다.

본 글에서 자세하게 언급하지 않는 테스트 코드 구성에 대한 Convention 및 방법들에 대해 잘 설명되어 있습니다.

Convention 부분만 간단히 말씀드리면 아래와 같습니다. 이 부분들은 단순히 Convention 뿐만 아니라 Test 수행할때 참고하는 부분이 되므로 꼭 기준에 맞춰서 만들어야 합니다.

1. test file 이름은 _test.go로 끝난다.
2. test file 내 Test Function 이름은 func TestXxx(*testing.T)로 구성한다. (X가 대문자를 의미)

간단히 1~n 까지 합을 구하는 함수를 만들고 테스트 코드를 구성해 보겠습니다.

sumnumbers.go

package main

func SumNumbers(n int) int {
	s := 0
	for i := 1; i <= n; i++ {
		s += i
	}
	return s
}

sumnumbers_test.go

package main

import "testing"

func TestSumNumbers(t *testing.T) {
	got := SumNumbers(10)
	if got != 55 {
		t.Errorf("SumNumbers(10) = %d; want 55", got)
	}
}

테스트 실행 : go test -run ‘’ -v

=== RUN   TestSumNumbers
--- PASS: TestSumNumbers (0.00s)
PASS
ok      test    0.005s

실행 방법에 대해서는 2.1. Test Execution 부분에서 언급하고 있기도 하고 이 단계는 단순한 결과만을 보여드리기 위함이니 그냥 넘어가셔도 좋습니다.

1.2. IDE(VS Code) 기능으로 자동 생성하기

글의 앞부분에서 이미 말씀드린 대로 VS Code는 Convention에 맞는 Unit Test 템플릿 코드를 자동으로 생성해주는 기능을 갖고 있습니다.

테스트 코드를 생성하고 싶은 부분의 함수명에서 마우스를 우클릭하고

Go: Generate Unit Tests For Function 을 선택해주면 자동으로 Convention에 맞는 파일 및 함수가 생성됩니다.

이때 자동으로 생성된 Unit 테스트 구성은 Table-driven 방식을 기본 골짜로 하여 생성됩니다.

sumnumbers_test.go

자동 생성된 결과에 Table driven 형태의 TC를 추가했습니다.

package main

import "testing"

func TestSumNumbers(t *testing.T) {
	type args struct {
		n int
	}
	tests := []struct {
		name string
		args args
		want int
	}{
		// TODO: Add test cases.
		{
			name: "TC1_TestSumNumbers: okcase",
			args: args{
				n: 10,
			},
			want: 55,
		},
		{
			name: "TC2_TestSumNumbers: okcase",
			args: args{
				n: 1,
			},
			want: 1,
		},
		{
			name: "TC3_TestSumNumbers: failcase",
			args: args{
				n: -10,
			},
			want: 55,
		},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			if got := SumNumbers(tt.args.n); got != tt.want {
				t.Errorf("SumNumbers() = %v, want %v", got, tt.want)
			}
		})
	}
}

테스트 실행 : go test -run ‘’ -v

=== RUN   TestSumNumbers
=== RUN   TestSumNumbers/TC1_TestSumNumbers:_okcase1
=== RUN   TestSumNumbers/TC2_TestSumNumbers:_okcase2
=== RUN   TestSumNumbers/TC3_TestSumNumbers:_failcase1
    main_test.go:40: SumNumbers() = 0, want 55
--- FAIL: TestSumNumbers (0.00s)
    --- PASS: TestSumNumbers/TC1_TestSumNumbers:_okcase1 (0.00s)
    --- PASS: TestSumNumbers/TC2_TestSumNumbers:_okcase2 (0.00s)
    --- FAIL: TestSumNumbers/TC3_TestSumNumbers:_failcase1 (0.00s)
FAIL
exit status 1
FAIL    test    0.005s

이런식으로 하나의 함수 안에서 단위테스트를 여러개를 구성할 수 있습니다. TC3_TestSumNumbers:_failcase1 는 의도적으로 테스트의 실패 케이스를 넣어 두었습니다.

2. 테스트 수행 방법 및 기능 살펴보기

2.1. Test Execution

테스트를 수행하는 다양한 방법 역시 testing package document에 잘 기술되어 있습니다. 이전 단계에서 skip, subtesting 등에 대해서 언급하지 않았으므로 해당 내용이 궁금하신 분은 testing package 링크 글을 참고하시기 바랍니다.

테스트를 수행할땐 다음과 같은 명령으로 수행합니다. -run 뒤의 값으로 테스트를 수행할 조건 대상을 선정할 수 있고 -v를 붙여주면 자세한 결과를 확인할 수 있습니다.

실행방법

go test -v -run ''  # Run all tests.
go test -v Foo      # Run top-level tests matching "Foo", such as "TestFooB -var".
go test -v Foo/A=   # For top-level tests matching "Foo", run subtests matching "A=".
go test -v /A=1     # For all top-level tests, run subtests matching "A=1".

기본적으로 특정 패키지의 파일들을 test하고 싶을 경우 해당 위치에서 go test -v 만 해도 쉽게 확인할 수 있습니다.

2.2. Code Coverage Testing

testing package를 통해 testcase를 구성하고 나면 code coverage또한 체크할 수 있는 이점이 있습니다. go blog Cover와 관련된 글을 참고하여 해당 내용을 정리해보도록 하겠습니다.

커버리지 측정 관련된 내용이므로 쉽게 확인하기 위해 예제 코드를 Cover 글에서도 이야기하고 있는 switch 문을 포함하는 예제로 살펴보겠습니다.

2.2.1. Test coverage for Go

예제 코드

package main

func Size(a int) string {
	switch {
	case a < 0:
		return "negative"
	case a == 0:
		return "zero"
	case a < 10:
		return "small"
	case a < 100:
		return "big"
	case a < 1000:
		return "huge"
	}
	return "enormous"
}

예제 테스트 코드

일부러 모든 경우를 충족시키지 않기 위해 negative, small 부분만 확인하도록 구성합니다.

package main

import "testing"

func TestSize(t *testing.T) {
	type args struct {
		a int
	}
	tests := []struct {
		name string
		args args
		want string
	}{
		{
			name: "negative check",
			args: args{-1},
			want: "negative",
		},
		{
			name: "small check",
			args: args{5},
			want: "small",
		},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			if got := Size(tt.args.a); got != tt.want {
				t.Errorf("Size() = %v, want %v", got, tt.want)
			}
		})
	}
}

실행 방법

go test -v -cover #(테스트 코드 경로)

실행 결과

=== RUN   TestSize
=== RUN   TestSize/negative_check
=== RUN   TestSize/small_check
--- PASS: TestSize (0.00s)
    --- PASS: TestSize/negative_check (0.00s)
    --- PASS: TestSize/small_check (0.00s)
PASS
coverage: 33.3% of statements
ok      test    0.005s

위 결과는 statement coaverage 측정 기준으로 33.3%를 충족하는 결과를 보여줍니다. 예상했던 대로 테스트 케이스를 충분하게 작성하지 않았기 대문에 모든 case를 돌지 못한 결과입니다.

coverage의 경우도 statment coverage 외에 다양한 기준과 방법이 존재하지만 여기서는 statement coverage만 다루도록 하겠습니다.

2.2.2. Viewing the results

golang에서 기본으로 제공하는 강력한 툴중에 cover라는 도구를 사용하면 정확히 어떤 영역들의 코드가 cover 되었는지를 아래와 같은 방법으로 확인할 수 있습니다.

-coverprofile 옵션으로 커버리지 정보를 추출한 파일을 생성합니다.
-func / -html 둘 중 하나의 옵션으로 상세 coverage 정보를 확인합니다.

coverprofile 생성

여기서 statement가 여러번 호출될 경우 진하게 표시하기 위해 -covermode=count를 추가했습니다.

go test -v -covermode=count -coverprofile=coverage.out

cover tool의 -func 옵션을 이용한 coverage 측정 결과

go tool cover -func=coverage.out

test/main.go:5: main            0.0%
test/size.go:3: Size            42.9%
total:          (statements)    33.3%

cover tool의 -html 옵션을 이용한 coverage 측정 결과

go tool cover -html=coverage.out

위 결과를 보면 어느 부분의 코드가 테스트되지 않았고, 어떤 식으로 테스트 케이스를 추가해야되는지 직관적으로 알 수 있습니다.

2.3. Benchmark Testing

기존의 테스트 코드에 아래의 Convention에 따라 필요한 내용을 추가하면 Benchmark Testing을 수행할 수 있습니다. Benchmark는 성능을 평가할때 사용하는데 활용될 수 있습니다.

1. test file 이름은 _test.go로 끝난다.
2. test file 내 Benchmark Function 이름은 func BenchmarkXxx(*testing.B)로 구성한다. (X가 대문자를 의미)

sumnumbers_test.go

func BenchmarkSumNumbers(b *testing.B) {

	for i := 0; i < b.N; i++ {
		SumNumbers(10)
	}
}

위 코드를 기존의 테스트 케이스에 혹은 새로 구성하여 반영해줍니다.

b.N 만큼 SumNumbers를 호출하여 성능을 평가한 뒤 결과로 알려주는데, b.N의 값은 본 코드를 쫒아가면 다음 주석이 있습니다. Run the benchmark for at least the specified amount of time.

테스트를 수행하는 환경에서 benchmark를 수행하기 위한 적당한 시간 및 횟수를 계산하고 그를 기준으로 benchmark 테스트를 합니다.

실행 방법

go test -bench=. #(테스트 코드 경로)

실행 결과

BenchmarkSumNumbers-12          361147497                3.295 ns/op
PASS
ok      test    1.534s

수행 결과로 361147497번의 호출을 했을때 평균 3.295 ns의 시간이 걸리는 것을 확인할 수 있습니다.

위 내용중에 b.N에 대해 아직 모호하게 생각되는 분들을 위해 아래 두 옵션을 추가로 소개해드립니다.

benchtime 옵션을 통해 시간 혹은 횟수를 지정하여 테스트할 수 있습니다.

명시적 횟수 지정 예 (10회)

go test -bench=. -benchtime=100x

명시적 시간 지정 예 (10초)

go test -bench=. -benchtime=10s

위 옵션으로 몇가지를 테스트 해보겠습니다.

명시적 횟수에 따른 벤치마크 테스트 (수행 시간을 주목해주세요)

go test -bench=. -benchtime=1x
BenchmarkSumNumbers-12                 1               246.0 ns/op

go test -bench=. -benchtime=10x
BenchmarkSumNumbers-12                10                25.40 ns/op

go test -bench=. -benchtime=100x
BenchmarkSumNumbers-12               100                 9.610 ns/op

go test -bench=. -benchtime=1000x
BenchmarkSumNumbers-12              1000                 4.072 ns/op

go test -bench=. -benchtime=100000x
BenchmarkSumNumbers-12            100000                 4.096 ns/op

go test -bench=. -benchtime=100000000x
BenchmarkSumNumbers-12          100000000                3.403 ns/op

go test -bench=. -benchtime=1000000000x
BenchmarkSumNumbers-12          1000000000               3.309 ns/op

benchmark 수행 횟수가 적을 수록 평균 시간이 엄청 느린 것을 알 수 있습니다. 1~1000회까지는 속도의 차이가 꽤 심하며, 그 이후로는 큰 차이를 보이지 않는것도 확인할 수 있네요.

수행 횟수에 따라 시간이 달라지는걸 예상해보면, 컴파일 이후 loader로 부터 메모리에 fetch 되고 실행 되는 과정이 한번 수행할때는 크게 영향을 주고, 많이 수행할땐 그 수로 나눠지면서 미미해지는게 아닌가 싶습니다.

예를들면 아래와 같습니다.

1회일 경우: (메모리 올라가는 시간 + 1번 수행 시간) / 1

100회일 경우: (메모리 올라가는 시간 + 100번 수행 시간) / 100

위 계산 방식으로 다항식을 실제 결과와 비교해보니 딱 들어맞지는 않습니다. 메모리에 올라가는 시간 말고 다른 영향을 미치는 부분이 있나봅니다.

명시적 시간 지정에 따른 벤치마크 테스트 (수행 횟수를 주목해주세요)

go test -bench=. -benchtime=0.001s
BenchmarkSumNumbers-12            290641                 3.964 ns/op

go test -bench=. -benchtime=0.01s
BenchmarkSumNumbers-12           3124398                 3.924 ns/op

go test -bench=. -benchtime=0.1s
BenchmarkSumNumbers-12          30180873                 3.577 ns/op

go test -bench=. -benchtime=1s
BenchmarkSumNumbers-12          350010990                3.399 ns/op

go test -bench=. -benchtime=2s
BenchmarkSumNumbers-12          706296723                3.319 ns/op

go test -bench=. -benchtime=3s
BenchmarkSumNumbers-12          1000000000               3.313 ns/op

go test -bench=. -benchtime=4s
BenchmarkSumNumbers-12          1000000000               3.310 ns/op

n초에 시행할 수 있는 횟수를 계산해서 benchmark를 수행해주는데, 재밌는건 2초까지는 횟수가 늘다가 3초부턴 상한 값이 정해져있는지 혹은 그이상 의미가 없는지 더 늘어나지 않는 모습을 알 수 있습니다.

정리해보면 benchmark에 별도로 benchtime 옵션을 주지 않으면 컴퓨터 환경에 따라 golang에서 알아서 계산 후 수행합니다. 혹시 benchmark 수행을 매번 돌리실 경우나 정확한 성능평가보단 추세를 보고싶으시다면 적당한 크기 (위 예제에선 1000 회 정도)로 지정해도 괜찮을 것 같네요.

3. 정리

비교적 간단한 내용이고 이미 공식 블로그나 다른 곳에서도 정리된 글들이 많이 보여서 글로 정리할 필요가 있을까 고민을 조금 했습니다. 하지만 중간 중간 궁금한 내용들을 찾아보고 그 부분만을 기록으로 남기면 누군가가 보았을때 그 흐름을 알지 못할수도 있겠다고 생각했습니다. 그리고 이 글을 계속 덧붙여 업데이트 해나갈 기준을 만들어 두고 싶었던 이유도 있습니다. 테스트와 관련해서는 앞으로도 꾸준히 글과 생각을 정리해서 올려보려고 합니다.

참고자료

https://golang.org/pkg/testing/

https://blog.golang.org/cover

Postman을 활용한 자동 REST API 테스트

Wed, 05 May 2021 00:00:00 +0000

postman과 newman cli를 활용하여 REST API를 테스트 하는 방법을 설명합니다.

0. 들어가기 전에

이번에는 REST API를 테스트하는 방법으로 Postma 툴을 활용하는 방법에 대해서 기술해보도록 하겠습니다. Postman 평소에 자주 사용하던 툴이기도 했는데, API를 시나리오 기반으로 자동으로 테스트하는 셋을 구성하고 싶은 생각에 몇몇 방법을 찾아봤으나, 해당 방법이 제일 간단한 것 같아서 정리합니다.

Postman에 대한 자세한 내용은 여기서 확인하실 수 있고 운영체제에 맞는 툴을 다운로드 받거나 웹 기반으로도 서비스를 제공하고 있습니다.

Postman 툴은 글 작성 시점 기준으로 무료이며, 원하는 추가 기능을 사용하려면 비용을 지불해야 합니다. 자세한 내용은 공식 홈페이지에서 참고하시기 바랍니다. 본 글은 무료 계정을 사용하였습니다.

1. Workspace 생성

위 화면 내용처럼 Workspace를 생성합니다. Visibility는 Personal, Team, Private, Public 에서 선택을 합니다.

2. API 요청 구성

요청할 API를 찾으신다면 네이버 개발자 센터 같은 곳에 친절하게 설명되어 있는 api들이 많습니다. 다만 저는 조금 간단히 하기 위해 웹 검색의 url을 그냥 가져와보도록 하겠습니다.

위 링크에 접속해보면 API 요청에 대한 정보를 얻을 수 있고 이 내용을 Postman에서 구성해보도록 하겠습니다.

강남역 맛집을 네이버에서 검색하면 위와 같이 GET 요청에 대한 URL이 생성됩니다. 이것을 Postman으로 요청해보겠습니다.

위와 같이 사용하는 법은 너무 간단합니다. URL을 붙여넣으니 쿼리 파라미터에도 자동으로 들어가는군요. 응답으로는 사용자들에게 보여줄 HTML 페이지 전문이 내려옵니다.

3. 테스트 셋 구성

그러면 이제 원래 하고싶었던 내용에 대해서 기술해보도록 하겠습니다. 서버를 배포할때 API에 대해서 테스트를 자동으로 해보고 싶을 경우 Postman에서 일부분 관련 기능을 제공해줍니다. 그 기능들에 대해 적어봅니다.

3.1 변수의 활용

먼저 테스트에도 활용될 수 있지만 변수에 대해서 이야기 해보려고 합니다. postman에서 변수 기능을 제공하고 있습니다.

위 화면처럼 우측 상단에 눈 모양의 버튼을 누르면 변수를 설정할 수 있는데, 이 기능은 나중에 자동화 테스트를 위해 collection을 export 해야하는데, Environment와 Globals 변수는 export에 포함되지 않습니다. 따라서 아래 화면의 박스쳐진 부분을 선택해서 반드시 Collection 변수로 설정해줍니다.

이런식으로 저장하면 아래와 같이 ** 을 통해 여러 곳에서 재사용 할 수 있습니다. 이 변수는 테스트케이스 구성에서도 사용될 예정입니다. 다만 Environment 변수나 Global 변수가 아닌 **Collection 변수로 지정했는지 다시 한번 확인해주시기 바랍니다.

잘 설정된 예 - C : Colllection 변수로 지정되어야 export에 포함됩니다.

잘못 설정된 예 - E : Environment나 Gloval 변수로 지정해서 사용하면 해당 작업환경에선 동작하지만 collection을 json으로 export 할때 포함되지 않아 문제가 발생합니다.

3.2 테스트 작성

오늘 주로 이야기하고 싶은 기능들은 모두 붉은색 네모 부분들입니다.

테스트 절차을 수행하기 위한 코드는 javascript로 구성됩니다. Tests를 누르면 나오는 화면에서 오른쪽 네모 박스 부분은 자주 쓰이는 테스트 구성에 대한 예제 인데 클릭하면 자동으로 관련된 javascript가 왼쪽 입력 칸에 들어오게 됩니다.

Tests 기능을 통해 http response code, body 등의 정보를 바탕으로 해당 요청이 성공적이었는지를 테스트 할 수 있습니다.

Pre-request Script 기능을 이용해 테스트의 Precondition을 수행할 수 있습니다. 변수를 지정한다던지 어떤 요청을 수행하기 전에 미리 설정을 진행할 수 있습니다.

3.2.1. Pre-request Script 구성

오른쪽 SNIPPET 구성에서 get an environment variable, set an environment variable 두 개를 이용해서 간단히 테스트해봅니다.

const TestInput1 = pm.environment.get("TestInput1");
pm.environment.set("TestInput1", TestInput1 + "네이버 맛집 검색결과");

위와 같은 코드를 구성하고 request를 반복해서 요청하면 실제 변수에 해당 값이 저장됨을 볼 수 있습니다.

3.2.2. Tests 구성

테스트 해볼 내용은 다음과 같습니다. 물론 기능의 동작을 확인하기 위한 내용이라 실제 테스트 설계 방법과 연관해서 생각하시지 않으셨으면 좋겠습니다.

TestInput1 변수의 내용에 네이버 맛집 검색결과 가 존재하는가
response code가 200으로 내려오는가
response body내 맛집 내용이 포함되어 있는가

const TestInput1 = pm.environment.get("TestInput1");

pm.test("TestInput1 contains 네이버 맛집 검색결과", function () {
  pm.expect(TestInput1).to.include("네이버 맛집 검색결과");
});

pm.test("Status code is 200", function () {
  pm.response.to.have.status(200);
});
pm.test("Body matches string", function () {
  pm.expect(pm.response.text()).to.include("맛집");
});

위 화면 결과처럼 각 테스트에 대한 결과를 확인할 수 있습니다.

3.3. 여러 테스트 동시 수행

왼쪽 화면 → 실행 Collection 마우스 우클릭 → Run collection

여러 테스트 진행을 확인하기 위해 지금까지 한 과정을 복사했습니다. 총 6개를 Run collection 하면 테스트 수행을 순차적으로 하고 이때 순서와 횟수 등을 변경할 수 있습니다. 그 결과로 레포트까지 얻을 수 있습니다.

4. 자동화 API 테스트와 CI/CD 연동

postman에서 collection을 cli로 실행할 수 있는 newman(npm/docker) 이라는 도구를 제공합니다. 이 도구를 활용한다면 기 작성한 postman collection을 활용하여 배포 과정에 API 테스트를 포함시킬 수 있습니다.

5. 정리

API 설계와 명세 그리고 테스트까지… postman 뿐만 아니라 swagger나 다른 툴 및 방법들을 사용해보았는데 각 도구가 저에게 딱 맞지 않고 조금씩 부족한 부분들이 있었던 것 같습니다. 그래서 저는 필요한 경우에 맞게 선택해서 사용하거나 섞어서 활용하고 있습니다.

하지만 이 글의 목적은 API 테스트 설계 도구로 Postman을 사용해보면 어떨까 에서 출발했고 그 간단한 사용법을 남기는 것이었습니다. SW 테스트와 관련해서 공부하다보면 늘 앞부분에 나오는 말중에 하나는 “완벽한 테스트는 없다” 인 것 같습니다. 그만큼 테스트를 많이 해도 완벽할 수 없다는 말인데, 그를 위해서 최소한 테스트를 쉽게 설계할 수 있는 도구나 방법이 중요하다고 생각합니다. 그런 이유로 Postman은 이런 요구를 충족할 수 있는 대안이 될 수 있을 것 같습니다.

참고자료

https://www.youtube.com/watch?v=z0MimkXIvE8

https://blog.postman.com/newman-run-and-test-your-collections-from-the-command-line/

https://dev.to/leading-edje/hello-newman-how-to-build-a-ci-cd-pipeline-that-executes-api-tests-2h5l

https://community.postman.com/t/how-do-i-set-a-collection-variable/5466

S3 파일 업로더 구성하기 (Cognito → S3)

Mon, 03 May 2021 00:00:00 +0000

Cognito를 활용해 client에서 file server를 거치지 않고 바로 S3로 저장하는 방법에 대해서 설명합니다.

S3 파일 업로더 구성하기 (Cognito → S3)

0. 시작하기 전에

본 글은 공식 가이드 문서를 참고하여 S3 파일 업로드 브라우저를 구성하는 과정을 기록합니다. 물론 공식 가이드 문서에 내용이 자세히 나와있으나, 잘 이해 안되거나 설명되지 않은 부분들 대해 이 글을 읽는 분들이 해소하실 수 있길 바라며 기록합니다.

먼저 해당 구성은 파일을 S3에 업로드 해야 하는 업무 요구사항이 있었습니다. 이를 위한 해결책으로 다음과 같은 방법들이 있었습니다.

FTP 서버 구성 후 cronjob 으로 S3로 전달
- 로그인/권한 문제 해결될 수 있으나, 파일 전달 목적의 비효울성이 발생합니다.
파일 서버 구성 후 S3로 전달
- S3의 버킷 정책이나 ACL 등을 고려하지 않고 S3에 접근 가능한 IAM 역할을 가진 ec2로 쉽게 전달할 수 있으나, 파일 전달 목적의 비효율이 발생합니다. (서버를 한번 거쳐서 S3로 전달하기 때문)
front page에서 client 차원으로 직접 S3로 파일 전달
- cognito, 권한 등을 고려해야 하는 문제가 있으나, client에서 직접 S3로 파일을 전달하므로 효율적입니다.

가장 빠르고 쉬운 방법으로 요구사항을 충족시킬 수 있는 구성을 택하려고 했고, 3번의 과정을 진행하면서 겪었던 내용을 기술합니다.

1. Building Block

Building Block이 이해가 안가는 부분이 있을 수 있을 것 같아 약간의 설명을 덧붙입니다.

EC2는 사실 프론트 서버를 띄우기 위해 구성했는데 어떤 방식으로 띄워도 상관 없습니다. (S3 static render, lambda 등)

User는 응답받은 front페이지에서 Javascript sdk로 Cognito에 S3 버킷에 접근 가능한 권한의 키를 이 프론트 페이지가 들고있는지 확인받습니다. (여기서 Cognito를 활용하는데 로그인 방식과 비로그인 방식이 존재합니다)

S3는 Public한 공간에서 요청이 들어올텐데 이를 제한하기 위해 액세스 차단과 관련된 설정이 필요합니다. (다운로드를 불가능하게 한다는 등의 조건)

2. 구성

2.1. S3 버킷 생성

Amazon S3 → Buckets → Create bucket

버킷 이름은 임의로 지정하고, 위와 같은 설정을 구성합니다.

여기서, 위 설정 내용을 조금 짚어봐야 할 것 같습니다. 필요한 내용은 붉은 글씨를 읽어주시기 바랍니다. 이 과정을 모두 거치고 나서 cognito를 이용한 파일 업로드는 성공했는데 외부에서 public url로 파일을 다운로드 못하도록 막고 싶었는데, ACL, bucket 정책 등에서 많이 헤매였던 경험이 있습니다.

2.2. S3 CORS 설정

Amazon S3 → Buckets → 생성한 Bucket → 권한 탭 → CORS 편집

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["HEAD", "GET", "PUT", "POST", "DELETE"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": ["ETag", "x-amz-meta-custom-header"]
  }
]

위 내용이 들어갈 수 있도록 CORS 를 설정해줍니다. CORS 관련된 자세한 내용은 여기를 참고하시면 됩니다.

2.3. Cognitio 설정

Cognito 페이지에 가보면 위 화면처럼 사용자 풀 관리와 자격 증명 풀 관리를 생성할 수 있습니다. 본 글에서는 자격 증명 풀 관리만을 사용하지만, 사용자 풀 관리를 활용해 Cognito 인증 기반 요청을 수행할 수 있습니다. 이 글은 비인증 기반 요청을 다루기 때문에 자격 증명 풀 관리를 선택합니다.

인증되지 않은 자격 증명에 대한 엑세스 활성화를 체크합니다.

이 내용은 Cognito를 통해 로그인 절차를 거친 뒤 얻은 key로 요청하는 방식과 로그인 하지 않고 자격증명 풀 관리 key만 가지고 요청하는 방식에 대해 어떻게 허용할 것인지에 대한 이야기 입니다. 저희는 별도로 로그인 과정을 거치지 않고 front 페이지에서 바로 요청할 것이기 때문에 비인증 자격 증명에 대한 엑세스 요청도 가능하도록 체크해줍니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["mobileanalytics:PutEvents", "cognito-sync:*"],
      "Resource": ["*"]
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:DeleteObject",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:PutObject",
        "s3:PutObjectAcl"
      ],
      "Resource": ["arn:aws:s3:::BUCKETNAME", "arn:aws:s3:::BUCKETNAME/*"]
    }
  ]
}

이 화면에서 세부 정보 숨기기(Hide Details)가 감춰져 있는데, 여기서 무시하고 허용 버튼을 누르면 나중에 IAM 에서 해당 역할을 추가해야 합니다. 번거로운 작업을 줄이기 위해 해당 화면의 Unauth_Role 부분의 Policy 부분에 위 내용으로 바꿔준 뒤 허용 버튼을 누릅니다.

생성하고 나면 위 화면과 같이 샘플 코드에 IdentityPoolId가 보입니다. 이 Id는 나중에 front page의 javascript 에서 사용할 예정이므로 메모해둡니다.

2.4. Front Server 구성

front page는 공식 가이드 문서에서 제공하는 코드를 사용합니다. 사진을 업로드 하는 html, js 코드로 구성되어 있습니다.

저는 위 코드와 더불어 python flask 기반으로 간단하게 서버를 띄우도록 하겠습니다. 아래 코드 중 경로와 s3_photoExample.js 코드의 BUCKET_NAME, REGION, IDENTITY_POOL_ID 정보를 각각 채워줍니다.

index.html 코드의 SDK_VERSION_NUMBER 부분도 변경해줘야 하는데 아래 코드는 이미 반영해두었으니 확인만 해주시기 바랍니다.

./app.py

from flask import Flask, render_template

app = Flask(__name__)

@app.route("/")
def index():
    return render_template("index.html")

if __name__ == "__main__":
    app.run(host="0.0.0.0", port="5000", debug=True)

./templates/index.html

<!DOCTYPE html>
<html>
  <head>
    <!-- **DO THIS**: -->
    <!--   Replace SDK_VERSION_NUMBER with the current SDK version number -->
    <script src="https://sdk.amazonaws.com/js/aws-sdk-sdk-2.283.1.min.js"></script>
    <script src="static/js/s3_photoExample.js"></script>
    <script>
      function getHtml(template) {
        return template.join("\n");
      }
      listAlbums();
    </script>
  </head>
  <body>
    <h1>My Photo Albums App</h1>
    <div id="app"></div>
  </body>
</html>

./static/js/s3_photoExample.js

var albumBucketName = "BUCKET_NAME";
var bucketRegion = "REGION";
var IdentityPoolId = "IDENTITY_POOL_ID";

AWS.config.update({
  region: bucketRegion,
  credentials: new AWS.CognitoIdentityCredentials({
    IdentityPoolId: IdentityPoolId,
  }),
});

var s3 = new AWS.S3({
  apiVersion: "2006-03-01",
  params: { Bucket: albumBucketName },
});

function listAlbums() {
  s3.listObjects({ Delimiter: "/" }, function (err, data) {
    if (err) {
      return alert("There was an error listing your albums: " + err.message);
    } else {
      var albums = data.CommonPrefixes.map(function (commonPrefix) {
        var prefix = commonPrefix.Prefix;
        var albumName = decodeURIComponent(prefix.replace("/", ""));
        return getHtml([
          "<li>",
          "<span onclick=\"deleteAlbum('" + albumName + "')\">X</span>",
          "<span onclick=\"viewAlbum('" + albumName + "')\">",
          albumName,
          "</span>",
          "</li>",
        ]);
      });
      var message = albums.length
        ? getHtml([
            "<p>Click on an album name to view it.</p>",
            "<p>Click on the X to delete the album.</p>",
          ])
        : "<p>You do not have any albums. Please Create album.";
      var htmlTemplate = [
        "<h2>Albums</h2>",
        message,
        "<ul>",
        getHtml(albums),
        "</ul>",
        "<button onclick=\"createAlbum(prompt('Enter Album Name:'))\">",
        "Create New Album",
        "</button>",
      ];
      document.getElementById("app").innerHTML = getHtml(htmlTemplate);
    }
  });
}

function createAlbum(albumName) {
  albumName = albumName.trim();
  if (!albumName) {
    return alert("Album names must contain at least one non-space character.");
  }
  if (albumName.indexOf("/") !== -1) {
    return alert("Album names cannot contain slashes.");
  }
  var albumKey = encodeURIComponent(albumName);
  s3.headObject({ Key: albumKey }, function (err, data) {
    if (!err) {
      return alert("Album already exists.");
    }
    if (err.code !== "NotFound") {
      return alert("There was an error creating your album: " + err.message);
    }
    s3.putObject({ Key: albumKey }, function (err, data) {
      if (err) {
        return alert("There was an error creating your album: " + err.message);
      }
      alert("Successfully created album.");
      viewAlbum(albumName);
    });
  });
}

function viewAlbum(albumName) {
  var albumPhotosKey = encodeURIComponent(albumName) + "/";
  s3.listObjects({ Prefix: albumPhotosKey }, function (err, data) {
    if (err) {
      return alert("There was an error viewing your album: " + err.message);
    }
    // 'this' references the AWS.Response instance that represents the response
    var href = this.request.httpRequest.endpoint.href;
    var bucketUrl = href + albumBucketName + "/";

    var photos = data.Contents.map(function (photo) {
      var photoKey = photo.Key;
      var photoUrl = bucketUrl + encodeURIComponent(photoKey);
      return getHtml([
        "<span>",
        "<div>",
        '<img style="width:128px;height:128px;" src="' + photoUrl + '"/>',
        "</div>",
        "<div>",
        "<span onclick=\"deletePhoto('" +
          albumName +
          "','" +
          photoKey +
          "')\">",
        "X",
        "</span>",
        "<span>",
        photoKey.replace(albumPhotosKey, ""),
        "</span>",
        "</div>",
        "</span>",
      ]);
    });
    var message = photos.length
      ? "<p>Click on the X to delete the photo</p>"
      : "<p>You do not have any photos in this album. Please add photos.</p>";
    var htmlTemplate = [
      "<h2>",
      "Album: " + albumName,
      "</h2>",
      message,
      "<div>",
      getHtml(photos),
      "</div>",
      '<input id="photoupload" type="file" accept="image/*">',
      '<button id="addphoto" onclick="addPhoto(\'' + albumName + "')\">",
      "Add Photo",
      "</button>",
      '<button onclick="listAlbums()">',
      "Back To Albums",
      "</button>",
    ];
    document.getElementById("app").innerHTML = getHtml(htmlTemplate);
  });
}

function addPhoto(albumName) {
  var files = document.getElementById("photoupload").files;
  if (!files.length) {
    return alert("Please choose a file to upload first.");
  }
  var file = files[0];
  var fileName = file.name;
  var albumPhotosKey = encodeURIComponent(albumName) + "/";

  var photoKey = albumPhotosKey + fileName;

  // Use S3 ManagedUpload class as it supports multipart uploads
  var upload = new AWS.S3.ManagedUpload({
    params: {
      Bucket: albumBucketName,
      Key: photoKey,
      Body: file,
    },
  });

  var promise = upload.promise();

  promise.then(
    function (data) {
      alert("Successfully uploaded photo.");
      viewAlbum(albumName);
    },
    function (err) {
      return alert("There was an error uploading your photo: ", err.message);
    }
  );
}

function deletePhoto(albumName, photoKey) {
  s3.deleteObject({ Key: photoKey }, function (err, data) {
    if (err) {
      return alert("There was an error deleting your photo: ", err.message);
    }
    alert("Successfully deleted photo.");
    viewAlbum(albumName);
  });
}

function deleteAlbum(albumName) {
  var albumKey = encodeURIComponent(albumName) + "/";
  s3.listObjects({ Prefix: albumKey }, function (err, data) {
    if (err) {
      return alert("There was an error deleting your album: ", err.message);
    }
    var objects = data.Contents.map(function (object) {
      return { Key: object.Key };
    });
    s3.deleteObjects(
      {
        Delete: { Objects: objects, Quiet: true },
      },
      function (err, data) {
        if (err) {
          return alert("There was an error deleting your album: ", err.message);
        }
        alert("Successfully deleted album.");
        listAlbums();
      }
    );
  });
}

3. 결과 확인

구성한 프론트페이지는 위 화면과 같이 뜨는 것을 확인해 볼 수 있습니다. 간단하게 폴더와 파일들을 조회하고 생성하고 삭제하고 업로드 하는 기능을 제공합니다.

그렇다면 업로드 된 파일을 public url로 다운로드 받아보는건 어떤지 확인해보도록 합니다.

1.jpeg라는 파일을 test 폴더를 생성하고 업로드 하면 S3 화면에서 Copy URL로 public url을 얻을 수 있습니다.

이제 이 항목을 다운로드 받아보도록 합니다.

브라우저에서 접속한 경우

wget https://file-uploader.s3.ap-northeast-2.amazonaws.com/test/1.jpeg
--2021-04-30 18:16:37--  https://file-uploader.s3.ap-northeast-2.amazonaws.com/test/1.jpeg
Resolving file-uploader.s3.ap-northeast-2.amazonaws.com (file-uploader.s3.ap-northeast-2.amazonaws.com)... 52.219.56.99
Connecting to file-uploader.s3.ap-northeast-2.amazonaws.com (file-uploader.s3.ap-northeast-2.amazonaws.com)|52.219.56.99|:443... connected.
HTTP request sent, awaiting response... 403 Forbidden
2021-04-30 18:16:37 ERROR 403: Forbidden.

wget 명령으로 터미널에서 다운로드 시도한 경우

두 경우 모두 의도한 대로 동작하는 것을 알 수 있습니다.

이 권한 설정은 2.1 버킷 생성 과정에서 설명된 ACL 권한과 관련이 있으므로 혹시 의도하시는 권한 설정이 있다면 다시 한번 보시기 바랍니다.

4. 개선 사항

혹시 위 코드를 조금 수정해서 급한대로 파일 업로더로 사용하고 싶으시다면 아래와 같은 부분들을 어렵지 않게 수정할 수 있습니다.

image 파일 외 다른 파일형식 업로드 가능하도록 변경 (input의 type 변경)

https://www.w3schools.com/tags/att_input_type_image.asp
여러 파일을 선택 가능하도록 변경 (input에 multiple 적용)

https://www.w3schools.com/tags/att_input_multiple.asp

업로드중인 파일의 업로드 진행 상황 표시하도록 변경 (putObject 및 httpUploadProgress 사용)

s3.putObject(
  {
    Key: fileKey,
    Body: file,
    ACL: "public-read",
  },
  (err, data) => {
    uploadStatusDone = true;
    viewFolder(folderName);
    addFiles(folderName, files, number + 1);
  }
).on("httpUploadProgress", (event) => {
  document.getElementById("uploadinfo").innerHTML =
    fileName +
    " " +
    ((event.loaded / event.total) * 100).toFixed(2) +
    "% " +
    "(" +
    (number + 1) +
    "/" +
    files.length +
    ")";
});

5. 생각해볼 점

5.1. 보안 취약점 (비인증 액세스 방식 도입)

먼저 위 방법은 굉장히 취약한 방법입니다. 따라서 급하게 사용하는 경우에 최소한 보안 그룹 등을 이용한 화이트리스트 접근 제어나, 간단한 형식의 페이지 접근 password를 걸어두시길 바랍니다. 그 이유는 만약 해당 페이지에 접근 가능하다면 마우스 우클릭으로 쉽게 javascript의 소스코드를 확인할 수 있고 그 결과 cognito ID 확인할 수 있습니다.

5.2. 개선 방법 (인증 액세스 방식 도입)

글 초입부에 짧게 언급하였는데 이러한 방법을 사용자 풀 관리 와 함께 인증 액세스 방식을 도입하면 개선할 수 있을 것 같습니다. 본 글에서 다루지는 않지만 나중에 다루더라도 함께 찾아봤던 글들을 여기에 남깁니다.

https://www.slideshare.net/awskorea/intro-to-amazon-cognito-2016

https://mygumi.tistory.com/362

5.3. 다른 방법

간단하게 누군가가 쉬운 방법으로 S3에 파일을 업로드 하는 것이 목적이라면 아래와 같은 방법들이 있습니다.

1.awslabs 에서 만든 repo (조회만 가능한 버전)

https://github.com/awslabs/aws-js-s3-explorer

2.awslabs 에서 만든 repo의 alpha branch (업로드 다운로드 가능한 버전)

https://github.com/awslabs/aws-js-s3-explorer/tree/v2-alpha

3.electron 기반 s3 upload app

https://www.electronjs.org/apps/s3uploader

위 내용들은 리서치 과정에서 찾은 대안들 이며 실제로 시도해보지는 않았음을 밝힙니다.

6. 정리

개발을 하다보면 자연스레 저장소에 업로드해야하는 요청이나 필요한 경우가 자주 발생하곤 합니다. 파일 업로드 기능을 수행하기 위해 세부 요구사항에 맞게 그때 마다 조금씩 설계를 다르게 하곤 하는데 가장 흔하게 사용될 수 있는 cloud저장소의 업로드 방법 중 AWS S3 업로드와 관련된 내용을 한번 정리해보았습니다.

References

https://docs.aws.amazon.com/ko_kr/sdk-for-javascript/v2/developer-guide/s3-browser-examples.html

https://mygumi.tistory.com/362

slideshare.net/awskorea/intro-to-amazon-cognito-2016

click log system 구성하기 (API Gateway → Kinesis → S3)

Sat, 01 May 2021 00:00:00 +0000

lambda 구성 없이 API Gateway, Kinesis Data Stream, Kinesis Data Firehose, S3로 click log 시스템을 구성하는 과정을 설명합니다.

0. 시작하기 전에

사용자가 application에서 특정 action을 했을 때 서버에 남을 api 로그와 별개로 사용자 행동과 관련된 로그를 별도로 저장하고 싶은 경우, 임의의 body 데이터를 의도한 공간에 저장하기 위한 경우의 시스템 구성에 대해 기록합니다.

1. Building block

다른 글들을 보면 kinesis 중간에 lambda가 handing 해주는 부분이 있는데 lambda 과정을 생략하는 방법을 다루고자 합니다.

본 글에서는 API Gateway를 통해 직접 kinesis data streams로 데이터를 전달하여 kinesis data firehose를 통해 S3로 stream data를 이관하는 방법을 기술하고자 합니다.

2. aws console로 구성하기

aws console은 aws 업데이트 마다 화면 구성이 및 기능들이 달라지겠지만, 직관적으로 작업할 수 있는 장점이 있기에 진행했던 내용을 정리하여 기술합니다.

2.1. IAM role 생성

2.1.1. 정책(Policy) 생성

Identity and Access Management(IAM) → 정책 → 정책 생성

위 화면에서 필요한 액세스 권한만을 부여하는 것이 맞지만 지금 과정은 테스트 과정이므로 모든 권한을 허용하는 것으로 진행해보도록 합니다.

위와 같이 정책 오류에 대한 메세지는 리소스에서 특정 혹은 모든 리소스에서 문제되는 부분을 해결할 수 있습니다.

[태그 추가는 건너 뛰도록 합니다.]

마지막으로 정책에 대한 이름을 지정하고 생성합니다.

2.1.2. 역할(Role) 생성

Identity and Access Management(IAM) → 역할 → 역할 생성

신뢰할 수 있는 유형의 개체를 선택합니다. 사용할 서비스에서 이 역할을 접근할 때 신뢰성을 보장하기 위해 선택합니다. 여기서는 API Gateway에서 역할을 사용할 것이므로 API Gateway를 선택합니다.

이후에 신뢰할 수 있는 서비스들을 json으로 더 추가할 수 있습니다. 만약 신뢰할 수 있는 서비스에 등록되지 않은 서비스에서 해당 권한으로 요청하게 되면 permission error가 발생하게 됩니다.

위 화면에서 보이는 정책이 CloudWatchLog 밖에 없을 수 있는데 일단 무시하고 생성한 뒤 이후에 정책을 연결 할 수 있습니다.

저는 위 화면처럼 권한 경계를 사용하여 최대 role개의 권한 제어를 선택하고 만들어둔 정책을 선택했는데 필수는 아닙니다.

마지막으로 역할에 대한 이름을 지정하고 생성합니다. 역할 설명은 원하는 내용으로 수정 변경합니다.

역할 생성이 완료되면 역할 ARN을 이후 Gateway API 진행 과정에서 사용하므로 별도로 메모해둡니다.

또한 정책 연결을 통해 생성한 정책을 역할과 연결해 줍니다.

2.2. Kinesis data streams 생성

Amazon Kinesis → 데이터 스트림 → 데이터 스트림 생성

테스트로 생성하는 목적이므로 샤드는 1개로 설정합니다. 샤드의 수가 많을 수록 허용하는 요청수가 늘어나게 됩니다. 이후 필요한 서비스의 목표에 따라 설정하도록 합니다.

2.3. API Gateway

API Gateway → API → API 생성

2.3.1. API Gateway 생성

REST API를 선택하여 구축합니다.

이 링크 글에 따르면, 아래와 같이 HTTP API가 기존의 REST API 보다 더 많은 기능, 더 낮은 지연 시간, 더 낮은 비용 을 위해서 추가된 기능이라고 하는데, 여기서는 kinesis를 구성하기 위해 REST API를 선택합니다.

With HTTP APIs, we have reduced request pricing to $1.00/million requests for the first 300 million requests, and $0.90/million for all requests after that. Most customers will see an average cost saving up to 70%, when compared to API Gateway REST APIs. In addition, you will see significant performance improvements in the API Gateway service overhead.

위와 같이 이름을 지정하고 생성합니다.

다음의 공식 가이드 문서에서 말하고 있는 기능들 중에 3번의 PutRecord를 api gateway와 연동하려고 합니다. 다른 기능들이 필요한 경우 본 글을 참고하여 가이드 문서를 따라 진행하시길 권장드립니다.

Kinesis의 ListStreams 작업
CreateStream, DescribeStream 또는 DeleteStream 작업
Kinesis의 GetRecords 또는 PutRecords(PutRecord 포함) 작업

위 기능에 대한 가이드문서의 리소스 구성은 다음과 같습니다

API의 /streams 리소스에 HTTP GET 메서드를 노출하고 메서드를 Kinesis의 ListStreams 작업과 통합하여 호출자 계정의 스트림을 나열합니다.
API의 /streams/{stream-name} 리소스에 HTTP POST 메서드를 노출하고 메서드를 Kinesis의 CreateStream 작업과 통합하여 호출자 계정에서 명명된 스트림을 생성합니다.
API의 /streams/{stream-name} 리소스에 HTTP GET 메서드를 노출하고 메서드를 Kinesis의 DescribeStream 작업과 통합하여 호출자 계정에서 명명된 스트림을 설명합니다.
API의 /streams/{stream-name} 리소스에 HTTP DELETE 메서드를 노출하고 메서드를 Kinesis의 DeleteStream 작업과 통합하여 호출자 계정에서 스트림을 삭제합니다.
API의 /streams/{stream-name}/record 리소스에 HTTP PUT 메서드를 노출하고 메서드를 Kinesis의 PutRecord 작업과 통합합니다. 그러면 클라이언트가 단일 데이터 레코드를 명명된 스트림에 추가할 수 있습니다.
API의 /streams/{stream-name}/records 리소스에 HTTP PUT 메서드를 노출하고 메서드를 Kinesis의 PutRecords 작업과 통합합니다. 그러면 클라이언트가 데이터 레코드 목록을 명명된 스트림에 추가할 수 있습니다.
API의 /streams/{stream-name}/records 리소스에 HTTP GET 메서드를 노출하고 메서드를 Kinesis의 GetRecords 작업과 통합합니다. 그러면 클라이언트가 지정된 샤드 반복기를 사용하여 명명된 스트림에 데이터 레코드를 나열할 수 있습니다. 샤드 반복기는 순차적으로 데이터 레코드 읽기를 시작할 샤드 위치를 지정합니다.
API의 /streams/{stream-name}/sharditerator 리소스에 HTTP GET 메서드를 노출하고 메서드를 Kinesis의 GetShardIterator 작업과 통합합니다. 이 헬퍼 메서드는 Kinesis의 ListStreams 작업에 제공되어야 합니다.

위 가이드 문서는 RESTful 한 구성으로 stream을 지정하여 CRUD 할 수 있도록 되어있는데, 여기서는 stream 이름을 지정하여 PutRecords 할 수 있는 기능을 연동 해보겠습니다.

2.3.2. Resource 구성

위 화면과 같이 리소스를 구성해 줍니다. 스트림을 직접 만든 kinesis로 지정할 것이기 때문에 가이드 문서에 나와 있는 {stream-name} 부분의 리소스 구성은 생략하도록 합니다.

2.3.3. Method 구성

Method를 생성하고 선택하면 아래 화면이 나오는데, 메서드 요청과 통합 요청을 각각 선택하여 다음의 설정들을 진행한다.

2.3.3.1. PUT - 메서드 요청

HTTP 메서드는 POST 입니다. 가이드 문서에 따르면 아래와 같이 언급하고 있습니다.

리소스에 HTTP PUT 메서드를 노출하고 메서드를 Kinesis의 PutRecord작업과 통합합니다. 그러면 클라이언트가 단일 데이터 레코드를 명명된 스트림에 추가할 수 있습니다.

API Gateway로 바깥으로 제공하는 method는 RESTful의 의미상 PUT으로, 내부적인 kinesis 동작을 위한 요청 method는 PutRecord 문서를 보면 POST로 전달하는 것을 볼 수 있습니다.

2.3.3.2. PUT - 통합 요청

매핑 템플릿 항목을 선택하고, Content-Type에 application/json을 추가한 뒤 템플릿 내용에 아래 정보를 저장 합니다.

어떤 stream에 요청할지에 대한 정보를 담고 있으며 KinesisDataStreamName 에는 생성한 stream의 이름을 지정해줍니다.

{
  "StreamName": KinesisDataStreamName,
  "Data": "$util.base64Encode($input.body)",
  "PartitionKey": "$context.requestId"
}

해당 정보에 대한 자세한 내용은 링크 글을 참고하시기 바랍니다.

3.3.3. PUT - 테스트

요청 본문에 아래와 같이 입력했는데, 오른쪽 로그를 살펴보면 통합 요청에서 추가했던 매핑 템플릿이 포함되어 전달된 것을 볼 수 있고, 응답 기대 결과로 ShardId가 내려온 것으로 보아 성공적으로 POS 요청이 동작하였음을 알 수 있습니다.

요청 본문

{
  "Data": "Test"
}

실제 요청 본문 로그

{
  "StreamName": "api-gateway-kinesis-test",
  "Data": "ewogICAgIkRhdGEiOiAiVGVzdCIKfQ==",
  "PartitionKey": "e000e702-1ed8-433b-8c8f-8e294684460c"
}

2.4. Kinesis data streams 데이터 확인

kinesis의 데이터를 가져오기 위해서 GetRecords 문서 를 보면 POST 요청에 다음과 같은 요청을 body에 포함해야 합니다.

ShardIterator가 required field 이며 원하는 kinesis stream의 ShardIterator를 알아야 해당 스트림에서 데이터를 꺼내올 수 있다는 의미입니다.

{
  "Limit": number,
  "ShardIterator": "string"
}

이를 위해 가이드 문서에서는 api gateway에 /streams/{stream-name}/sharditerator 이 리소스의 구현을 통해 연동하는 것을 가이드 하고 있습니다.

본 글에서는 해당 내용을 연동하지 않고, aws cli를 통해 간단히 stream의 데이터를 확인할 수 있는 방법을 진행하고자 합니다.

2.4.1. ShardIterator 요청

요청

aws kinesis get-shard-iterator \
--stream-name api-gateway-kinesis-test \
--shard-id shardId-000000000000 \
--shard-iterator-type AT_TIMESTAMP \
--timestamp 1609489201

stream-name : kinesis stream 이름

shard-id : PutRecord 결과로 받은 응답 shardId

teimstamp : unix epoch time으로 해당 시간 이후로 요청된 내용을 가져오기 위함

응답

{
  "ShardIterator": "AAAAAAAAAAETNsov/ad8I319/hcr67iF+GXRfWPGKddiRLLryOUdajcITPhRItI09YJd9ENy4PLyjP0WRxr0ljrFDdRqO6b3FY1tDtt86VMjQEEDSma+LAqSBgz7buORcglJRn8MgDXLLnWJsTlG0uDauZnDi4tfCCnrLDr3FrYO1vOA4j+eAi4fiPDYzuWNH/3BtbocoFn3PrrG/2Nwf3S+oSeu6wpbGrGyrpqWHtD42l2MRGDCyH3d6vq5eQCk2forH0oEh0Rk2B/Uw5P3cIJ4K1UDzEYO"
}

2.4.2. GetRecords

요청

aws kinesis get-records \
--shard-iterator AAAAAAAAAAETNsov/ad8I319/hcr67iF+GXRfWPGKddiRLLryOUdajcITPhRItI09YJd9ENy4PLyjP0WRxr0ljrFDdRqO6b3FY1tDtt86VMjQEEDSma+LAqSBgz7buORcglJRn8MgDXLLnWJsTlG0uDauZnDi4tfCCnrLDr3FrYO1vOA4j+eAi4fiPDYzuWNH/3BtbocoFn3PrrG/2Nwf3S+oSeu6wpbGrGyrpqWHtD42l2MRGDCyH3d6vq5eQCk2forH0oEh0Rk2B/Uw5P3cIJ4K1UDzEYO

응답

{
  "Records": [
    {
      "SequenceNumber": "49617687179155666429430101670197006370059396208769630210",
      "ApproximateArrivalTimestamp": 1619426371.64,
      "Data": "e30=",
      "PartitionKey": "04294d1f-491d-4ea9-8e28-8923e48d9d2b"
    },
    {
      "SequenceNumber": "49617687179155666429430101670198215295879010975383289858",
      "ApproximateArrivalTimestamp": 1619426373.735,
      "Data": "e30=",
      "PartitionKey": "8130f87d-fc2b-410f-8a22-9a288b8fc11d"
    },
    {
      "SequenceNumber": "49617687179155666429430101670199424221698625673277472770",
      "ApproximateArrivalTimestamp": 1619426374.598,
      "Data": "e30=",
      "PartitionKey": "70d2ec6e-e74f-43f3-94ea-b5b97b779277"
    },
    {
      "SequenceNumber": "49617687179155666429430101670200633147518240302452178946",
      "ApproximateArrivalTimestamp": 1619426374.803,
      "Data": "e30=",
      "PartitionKey": "888809c6-98a7-4c2a-9170-c4988bd13339"
    },
    {
      "SequenceNumber": "49617687179155666429430101670201842073337854931626885122",
      "ApproximateArrivalTimestamp": 1619426374.97,
      "Data": "e30=",
      "PartitionKey": "22601971-e0a1-4749-8b34-18178ae33427"
    }
  ],
  "NextShardIterator": "AAAAAAAAAAH7+NNTZsDi9Sh5qwpc1/mO0f86w56xSq8vkSjHWSxgBzSqZdiTtg89qFTaHfA89m2dwGmGutxeO+2kA7naO0XDlHYE80UywWV6TPmlQBJ54jo6D5ke1hKeZoYQq78jWdf6BdXS8CF4UM3BgmoNyxwKIMZg/aMxNO5H5a9gpaFEZHnIlDwz3ygbdTXFyCjhXcAL+mlmyoF8VmUMZp/Tk85jymj/htqwzrxOYlk2zc27bN5EE48CL0TP45FfUg0nX9Q=",
  "MillisBehindLatest": 0
}

위 결과는 해당 스트림에 저장된 데이터의 정보를 출력한 것을 나타냅니다.

2.5. S3 버킷 생성

Amazon S3 → 버킷 만들기

화면과 같이 원하는 이름의 bucket을 생성합니다. 다른 bucket 설정은 변경하지 않아도 됩니다.

2.6. Kinesis data filehose 생성

Amazon kinesis → Data Firehose → Create delivery stream

2.6.1. Source stream 지정

Kinesis Data Stream을 선택하고, 기존에 생성한 stream을 지정하면 lambda 없이 firehose에서 S3로 stream data를 옮길 수 있습니다.

2.6.2. Process records 옵션

lambda function을 통해 transform이나 convert 동작을 수행할 수 있는 옵션을 제공하는데, 지금은 사용하지 않고 넘기기로 합니다.

2.6.3. Destination 지정

s3로 저장하는 것이 목표이므로 이전 단계에서 만들었던 S3 bucket을 지정하여 설정합니다.

2.6.4. configure 설정

buffer size와 buffer interval 둘 중 하나의 옵션으로 s3로 저장하는 동작이 trigger 됩니다.

위 내용대로라면 5MB 혹은 300sec 넘어갈 경우 s3로 stream 데이터가 이동하게 됩니다.

2.7. S3 저장 결과 확인

위 화면과 같이 최종 결과로 stream data가 s3에 저장된 것을 볼 수 있습니다. 1MB, 60sec 값으로 kinesis firehose의 설정을 반영한 결과 입니다.

3. 정리

처음엔 AWS 공식 가이드 문서를 쫒아서 진행하는데 의도한대로 잘 동작하지 않았습니다.

같은 문제를 겪는 분들이 있을 것 같아 리서치를 했고 부분마다 안되는 곳들을 찾아서 순서대로 진행해 보았습니다.

처음엔 시간이 지나면 이 글대로도 동작하지 않을 것 같아서 console, cli, serverless 혹은 cdk로 구성하는 방법을 모두 기록으로 남길까 고민했습니다.

하지만 이후 시스템 기능의 변화가 있더라도 큰 흐름은 바뀌지 않을 것 같고 console로 구성하면서 그 과정을 이해한다면 cli나 cdk 등의 구성에서도 큰 어려움을 느끼지 않을 것이라고 생각하여 이쯤에서 마무리 지으려고 합니다.

참고자료

https://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/integrating-api-with-aws-services-kinesis.html

https://haandol.github.io/2020/07/28/apigateway-kinesis-logging.html

https://chang12.github.io/api-gateway-kinesis-proxy/

https://joobly.tistory.com/22

AWS API Gateway 고정 IP 만들기 (NLB → VPC endpoint → API Gateway)

Sat, 01 May 2021 00:00:00 +0000

NLB, VPC endpoint, API Gateway를 활용하여 AWS API Gateway의 IP를 고정 IP로 만드는 과정을 설명합니다.

0. 시작하기 전에

API Gateway의 IP가 고정이든 유동이든 큰 신경쓸 필요가 없는 경우가 대부분이긴 합니다. 하지만 회사 보안 정책이나 특정 시스템의 방화벽 허용을 위한 예외 처리를 화이트 리스트로 관리해야 한다면, IP는 아무래도 고정으로 지정되어 있어야 관리하기 편합니다.

현재 글 작성 시점 기준으로 AWS에서 해당 기능을 편리한 방법으로 제공하지 않고 있으며 여러가지 쉽고 어려운 방법들이 존재하는데, 그 중 구조상 제일 괜찮은 것으로 생각되는 아래 구성에 대한 기록을 남깁니다.

Route 53/Domain → NLB → VPC Endpoint → API Gateway(Private)

1. 문제의 인식

https://google.com 으로 GET 요청을 날리는 간단한 API 를 하나 정의하고 배포해보도록 하겠습니다.

그 결과 https://344i1vresf.execute-api.ap-northeast-2.amazonaws.com/test API주소를 얻었습니다.

위 주소는 글 작성 이후 삭제될 예정이므로 호출하셔도 올바른 응답을 얻을 수 없습니다.

문제의 현상을 보기 위함이니 참고용으로 보시면 될 것 같습니다.

요청

curl -X GET https://344i1vresf.execute-api.ap-northeast-2.amazonaws.com/test

응답

<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8">
<TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>
The document has moved
<A HREF="https://www.google.com/">here</A>.
</BODY></HTML>

응답 결과가 301로 떨어지는걸로 봐서 API Gateway는 잘 연동되었다는 것을 알 수 있습니다.

이제 테스트 환경은 끝났고,

https://344i1vresf.execute-api.ap-northeast-2.amazonaws.com 주소의 실제 IP를 확인해보겠습니다.

nslookup 혹은 dig을 이용하여 확인합니다.

$dig [344i1vresf.execute-api.ap-northeast-2.amazonaws.com](http://344i1vresf.execute-api.ap-northeast-2.amazonaws.com/)
$nslookup [344i1vresf.execute-api.ap-northeast-2.amazonaws.com](http://344i1vresf.execute-api.ap-northeast-2.amazonaws.com/)

[1회차 요청]
nslookup 344i1vresf.execute-api.ap-northeast-2.amazonaws.com
Server:		192.168.10.1
Address:	192.168.10.1#53

Non-authoritative answer:
Name:	344i1vresf.execute-api.ap-northeast-2.amazonaws.com
Address: 3.35.86.48
Name:	344i1vresf.execute-api.ap-northeast-2.amazonaws.com
Address: 52.78.233.230

---------------

[2회차 요청]
nslookup 344i1vresf.execute-api.ap-northeast-2.amazonaws.com
Server:		192.168.10.1
Address:	192.168.10.1#53

Non-authoritative answer:
Name:	344i1vresf.execute-api.ap-northeast-2.amazonaws.com
Address: 3.34.120.247
Name:	344i1vresf.execute-api.ap-northeast-2.amazonaws.com
Address: 52.78.33.158

---------------

[3회차 요청]
nslookup 344i1vresf.execute-api.ap-northeast-2.amazonaws.com
Server:		192.168.10.1
Address:	192.168.10.1#53

Non-authoritative answer:
Name:	344i1vresf.execute-api.ap-northeast-2.amazonaws.com
Address: 3.36.158.122
Name:	344i1vresf.execute-api.ap-northeast-2.amazonaws.com
Address: 3.36.30.67

위 결과의 Non-authoritative answer 부분을 보시면 응답 서버의 IP가 계속 바뀌어 내려오는 것을 확인할 수 있습니다. 따라서 AWS API Gateway는 고정 IP로 사용자들에게 API 서비스를 제공하지 않는다는 것을 확인할 수 있습니다.

2. Building Block

NLB와 API Gateway의 위치가 위 그림과 정확히 일치하지 않지만 전체적인 동작의 이해를 돕기 위해 Subnet 구성을 통합하고 그 안에 블록을 포함시켰습니다.

실제 시스템을 구성하게 될 순서는 API Gateway → VPC Endpoint → NLB → DNS 연결 순으로 위 그림 기준 오른쪽에서 왼쪽으로 구성합니다.

3. 구성

VPC 구성은 아래와 같이 이미 완료되어있는 것을 가정하며 본 글에서 VPC 구성 방법은 다루지 않으나, 이후 다른 글에서 다루어 보도록 하겠습니다.

3.1. API Gateway 생성

API Gateway → API → API 생성

위 화면에서 네번째 항목인 REST API 프라이빗 을 선택해 API 를 생성합니다.

엔드포인트 유형의 설명을 보면 REST API 프라이빗 으로 만든 API 는 API Gateway용 VPC 엔드포인트를 통해서만 엑세스 할 수 있다는 것을 주의깊게 보셔야 합니다. 외부에서 직접 호출이 불가능하며 VPC 엔드포인트와 연동이 필요합니다.

문제의 인식 부분에서 사용했던 테스트용 Get Method를 위 내용과 같이 정의한 뒤에 배포합니다.

api gateway 생성 시 지정했던 vpceID를 에 넣어 해당 정책을 ResourcePolicy에서 반드시 추가시켜줘야 합니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": "*",
            "Action": "execute-api:Invoke",
            "Resource": [
                "execute-api:/*"
            ]
        },
        {
            "Effect": "Deny",
            "Principal": "*",
            "Action": "execute-api:Invoke",
            "Resource": [
                "execute-api:/*"
            ],
            "Condition" : {
                "StringNotEquals": {
                    "aws:SourceVpce": ""
                }
            }
        }
    ]
}

3.2. VPC Endpoint 생성

서비스 이름은 execute-api가 포함된 것을 선택합니다.

원하는 VPC를 선택한 뒤 서브넷을 선택할때 API Gateway를 통해 private 영역에 있는 API를 호출하려고 하면 private 영역을 선택해야 합니다. 여기서는 private 영역을 선택해줍니다.

보안 그룹은 필요한 경우 원하는 보안 그룹을 지정합니다.

VPC Endpoint를 생성하고 나면 위 화면과 같이 private zone에 해당하는 ip가 임의로 할당된 것을 볼 수 있습니다.

3.3. Network Load Balancer 생성 및 Elastic IP 연결

3.3.1. Elastic IP 생성

네트워크 및 보안 → 탄력적 IP → 탄력적 IP 주소 할당

NLB 생성 과정에서 탄력적 IP 주소를 사용할 수 있도록 지정하는 화면이 있기 때문에, 미리 만들어둡니다. 해당 과정에서는 a zone, c zone에서 사용할 두개의 static ip를 생성합니다.

3.3.2. Network Load Balancer 생성

EC2 → 로드 밸런싱 → 로드밸런서 → Load Balancer 생성

Network Load Balancer를 선택하여 생성합니다.

3.3.2.1. 기본 설정

3.3.2.2. Network mapping

3.3.2.3. Listeners and routing

위 화면에서 Create target group 을 선택하여 대상 그룹을 생성하고 VPC Endpoint로 routing 할 IP 들을 지정해주어야 합니다.

3.3.2.4. Traget group

위 화면은 대상 그룹의 생성 화면인데 특별한 내용 없이 저정하고 다음으로 넘어갑니다.

위 화면과 같이 IP 부분에 VPC Endpoint 때 자동으로 생성되었던 IP들 (a zone, c zone 모두)을 등록해줍니다.

이후 NLB 생성을 완료해줍니다.

이후 대상 그룹에서 health check가 healthy(green)으로 불이 들어오면 NLB → StaticIP → 대상그룹 → VPC End Point 까지 연결이 잘 되었다고 생각할 수 있습니다.

3.4. 동작 확인

curl -k -H "Host : {api gateway 주소}" https://{nlb 주소}/{api gateway stage}

사용자 지정 도메인 이름을 연동하기 전에 NLB 주소로 API Gateway를 호출해보고자 한다면 위의 방식으로 테스트 해볼 수 있습니다.

여기서 드는 의문점은 VPC Endpoint와 API Gateway를 연결한 적이 없이 없는데 어떻게 호출할 수 있지 라는 생각이 들 수 있습니다.

직접 연결하지 않아도 API Gateway를 호출할 수 있는데 NLB를 통해 호출해야 하는 과정을 위해 Header의 Host 필드에 요청할 API Gateway 주소를 지정해야 합니다.

이 다음 단계에서 도메인과 API Gateway를 연결하게 되면 도메인을 통해 헤더 없이 직접 호출할 수 있게 됩니다.

3.5. 사용자 지정 도메인 이름

위 화면은 API Gateway 화면에서 왼쪽에 위치한 사용자 지정 도메인 이름 을 선택했을때 나오는 화면이며,

도메인과 관련된 내용을 추가하여 생성하고 생성된 항목을 선택하면 API Gateway의 배포된 Phase와 연동할 수 있습니다.

해당 도메인 주소에 NLB 주소의 CNAME을 Route53에도 추가해줍니다.

이 과정을 끝내면 생성한 도메인으로 일반적인 방식으로 API 요청을 할 수 있습니다.

4. 정리

위 과정을 진행하고 나면 NLB에 지정한 도메인을 dig 혹은 nslookup을 통해 요청해보면 nlb 생성 시 지정한 Elastic IP로 일관된 IP로부터의 응답을 내려주는 것을 볼 수 있습니다.

이후 AWS에서 API Gateway의 IP를 고정으로 내려주는 기능이 추가될 지 모르겠으나 현재로서는 해당 구조가 제일 문제가 발생하지 않을 구조라 판단하여 조사한 자료들을 바탕으로 구성한 기록을 남깁니다.

참고자료

https://zenliu.medium.com/how-to-assign-elastic-ip-to-amazon-api-gateway-ddbee9146bec

https://medium.com/opseco-technologies/assign-fixed-ip-to-aws-api-gateway-fb72507a2883

Go 동시성 패턴 - Pipelines and cancellation (fan in/fan out)

Thu, 15 Apr 2021 00:00:00 +0000

Golang 동시성 패턴 중 channel을 활용한 fan in/ fan out에 대한 내용을 설명합니다.

Go 동시성 특성

I / O 및 다중 CPU를 효율적으로 사용하는 스트리밍 데이터 파이프 라인을 쉽게 구성 할 수 있습니다.

파이프라인

golang에서 공식적인 개념의 파이프라인은 정해진 것이 없고, 일반적으로 채널로 연결된 일련의 단계를 파이프라인 이라고 일컫습니다.

또한 각 단계는 동일한 기능을 수행하는 고루틴 그룹입니다.

인바운드 채널을 통해 업스트림에서 값 수신 (소스 또는 생산자) - 1단계
해당 데이터에 대해 일부 기능을 수행하여 일반적으로 새로운 값을 생성합니다. - 2단계
아웃 바운드 채널을 통해 값을 다운 스트림으로 전송 (싱크 또는 소비자) - 3단계

위 내용을 이해한 바를 그림으로 표현하면 아래와 같습니다.

upstream 과 downstream을 이해하기 쉽게 step을 이어서 그리지 않고 나누어 표현했습니다.

실제 사례에 활용하는 방법을 위해, kakao, naver, google로 특정 검색을 요청하고 결과를 취합하는 예제를 구성하며 살펴보도록 하겠습니다.

step 1 : producer

producer는 입력 데이터에 대한 channel 들을 생성합니다.

생성한 채널을 이용해 이후 fan out 단계에서 함수들이 해당 채널로부터 값을 가져갑니다.

이 예제에서는 카카오, 구글, 다음 웹사이트의 주소를 파라미터로 받아 각각에 대한 채널을 생성합니다.

func produceChan(done <-chan struct{}, urls []string) <-chan string {

	// 값을 보낼 목적의 channel을 생성한다.
	outChan := make(chan string, 3)

	// 생성한 channel로 요청이 필요한 url 들을 보낸다.
	go func() {
		// <-done에 의해 갑자기 종료되는 경우에 chan을 close 한다.
		defer close(outChan)
		for _, url := range urls {
			select {
			case outChan <- url:
			case <-done:
				return
			}
		}
	}()

	return outChan
}

step2-1 : fan out

fan out은 채널이 닫히기 전까지 채널 안에 있는 값들을 여러 함수들이 꺼내올 수 있는 것을 말합니다.

하나의 채널 안에 있는 값들을 꺼내서 여러 함수에서 동시적 처리가 가능합니다.

이 예제에서는 카카오, 구글, 다음 웹사이트로 동시에 http get 요청을 합니다.

func fanOut(done <-chan struct{}, outChan <-chan string) <-chan string {

	// 값을 받을 목적의 channel을 생성한다.
	inChan := make(chan string, 3)

	// 동시에 수행해야 하는 operation을 처리한다. 여기서는 http request get 요청을 수행한다.
	go func() {
		// <-done에 의해 갑자기 종료되는 경우에 chan을 close 한다.
		defer close(inChan)
		for url := range outChan {

			resp, err := http.Get(url)
			if err != nil {
				fmt.Println(err)
			}
			defer resp.Body.Close()

			data, err := ioutil.ReadAll(resp.Body)
			if err != nil {
				fmt.Println(err)
			}

			select {
			case inChan <- string(data):
			case <-done:
				return
			}
		}
	}()

	return inChan
}

step2-2 : fan in

fan in은 단일 채널에 fan out때 요청했던 결과들을 입력으로 받아 하나로 모을 수 있습니다.

여기서 fan out의 결과인 입력 채널들이 모두 닫힐때까지 (작업이 완료 될 때 까지) 기다려주는데, sync.WaitGroup을 이용해서 모든 입력 채널들의 작업이 완료되는 것을 기다립니다.

그 결과로 fan in의 outbound chan은 카카오, 구글, 다음의 response body 결과를 들고있게 됩니다.

func fanIn(done <-chan struct{}, outChan ...<-chan string) <-chan string {

	// 동기화를 위해 waitgroup를 사용한다.
	var wg sync.WaitGroup

	// 결과를 합칠 채널을 생성한다.
	merged := make(chan string, 3)

	wg.Add(len(outChan))

	outChanMerge := func(oc <-chan string) {
		// <-done에 의해 갑자기 종료되는 경우에 wait group을 종료한다.
		defer wg.Done()

		// outChan으로부터의 결과를 merge 하는 채널로 전달한다.
		for n := range oc {
			select {
			case merged <- n:
			case <-done:
				return
			}
		}
	}

	for _, ch := range outChan {
		go outChanMerge(ch)
	}

	// 모든 요청에 대한 응답을 동기화하여 합치기 위해 기다린다.
	go func() {
		defer close(merged)
		wg.Wait()
	}()

	return merged
}

step 3 : consume

consume 단계는 fan out/ fan in 과정을 통해 취합된 결과들이 outbound channel에 담겨있는데, 이를 꺼내 활용하는 과정입니다.

func consumeChan(outChan <-chan string) []string {

	result := make([]string, 0, 0)

	for body := range outChan {
		result = append(result, body)
	}
	return result
}

step 4: main 호출

실제로 앞의 과정들을 호출하는 코드는 아래와 같습니다.

done 의 언급에 대해서 본글에 설명이 안되어있는데, 간략히 말씀드리자면, chan 을 통해 데이터를 주고받는 경우 많은 주의를 기울여야 합니다.

의도하지 않게 inbound channel에서 데이터를 무한정 기다리게 될 수도 있고, 닫힌 channel에 값을 넣어버리면 panic이 나는 경우 등이 있기 때문입니다.

이중에 무한정 기다리게되는 hang을 피하기 위해 done 이라는 채널을 두어 명시적 취소 절차를 진행할 수 있습니다.

자세한 내용은 원글 블로그에 자세히 나와있으므로 참고해보시면 좋을 것 같습니다.

func main() {
	done := make(chan struct{})
	defer close(done)

	inChan := produceChan(done, []string{"https://naver.com", "https://google.com", "https://www.daum.net"})
	f1 := fanOut(done, inChan)
	f2 := fanOut(done, inChan)
	f3 := fanOut(done, inChan)

	outChan := fanIn(done, f1, f2, f3)
	result := consumeChan(outChan)

	for _, body := range result {
		fmt.Println(body)
	}
}

참고자료

https://blog.golang.org/pipelines

Explore, Dream, Discover

redis - sharding

TL; DR

What is Sharding?

Pros & Cons

Pros

Cons

Sharding Strategies

키 기반 샤딩(Key-based Sharding)

범위 기반 샤딩(Range-based Sharding)

디렉토리 기반 샤딩(Directory-based Sharding)

References

redis - hashtag

TL;DR

Hashslot

Refrences

go-redis - go-redis v9 에서 hash 타입을 다루는 방법

TL;DR

Overview

Usage

go-redis/v8 이하

go-redis/v9 이상

Benchmark

Conclusion

References

redis - cluster mode

What is Cluster Mode?

Redis Mode 별 차이 비교

redis-cli로 cluster mode 환경 살펴보기

References

redis - key rules

TL; DR

Keyspace

Kong Gateway 4. Kong Auth Plugin 연동하기

Kong Gateway #4 Kong Auth Plugin 연동

0. 들어가기 전에

1. Authentication(인증) vs Authorization(인가)

2. 인증 및 인가 과정

3. 인증 플러그인 종류

4. 기본 제공 플러그인 연동

4.1. 사용할 예제 및 준비

4.2. 인증 유형별 요청 방법

basic-auth

key-auth

hmac-auth

jwt

oauth2

4.3 Basic Auth 테스트

4.4 API Key 테스트

4.5 HMAC 테스트

5. 정리

6. 참고

ArgoCD 2. ArgoCD Slack Notification

0. 들어가기 전에

1. 문제의 발생

2. 처음부터 짚어보기

2.1 slack 봇 생성

2.2 Kubernetes에 notifier 및 template 설치하기

2.2.1 argocd-notifications-secret.yaml (신규 생성)

2.2.2 notification.yaml

2.2.3 templates.yaml

2.3 트리거 등록

2.3.1 kubectl 로 argo app에 annotation을 추가하는 방법

2.3.2 argocd admin 페이지에서 annotation을 추가하는 방법

3. Trouble shooting

3.1 argocd-notifications-controller pod의 로그

3.2 argocd app이 보이지 않는 경우

4. 정리

5. 참고자료

ArgoCD 1. ArgoCD 구성하기

0. 들어가기 전에

1. CD in DevOps

2. ArgoCD

3. CD 구성

3.1 GitOps 구성

3.2 ArgoCD 설치

3.2.1 Kubernetes에 ArgoCD 설치

3.2.2 admin 계정 설정

4. ArgoCD 살펴보기

4.1 ArgoCD 접속

Usage