다음 명령을 사용하여 Teleport와 같은 네임스페이스에 데이터베이스 CA 인증서가 포함된 시크릿을 생성합니다:

$ kubectl create secret generic db-ca --from-file=ca.pem=/path/to/oracle-server-certificate.crt

다음 내용으로 values.yaml 파일을 생성합니다. 을 tctl tokens add 명령으로 생성한 조인 토큰으로 업데이트합니다:

roles: db
proxyAddr: 






Flag
Description




--roles
List of roles to assign to the user. The builtin access role allows them to connect to any database server registered with Teleport.


--db-users
List of database usernames the user will be allowed to use when connecting to the databases. A wildcard allows any user.


--db-names
List of logical databases (aka schemas) the user will be allowed to connect to within a database server. A wildcard allows any database.




For more detailed information about database access controls and how to restrict
access see RBAC documentation.

6/6단계. 연결#
Database Service가 클러스터에 참여하면 로그인하여 사용 가능한 데이터베이스를 확인합니다:
$ tsh login --proxy= --user=alice
$ tsh db ls
# Name   Description    Allowed Users Labels  Connect
# ------ -------------- ------------- ------- -------
         [*]                   env=dev

"" 데이터베이스에 연결합니다. --db-name 파라미터로 올바른 서비스 이름을 전달합니다.
Oracle Exadata VM에서 데이터베이스 구성을 검사하여 서비스 이름을 확인할 수 있습니다.
> lsnrctl services | grep paas
Service "spark_PDB1.paas.oracle.com" has 1 instance(s).

$ tsh db connect --db-user alice --db-name spark_PDB1.paas.oracle.com 
# SQLcl: Release 24.2 Production on Fri Aug 09 15:29:41 2024
#
# Copyright (c) 1982, 2024, Oracle.  All rights reserved.
#
# Connected to:
# Oracle Database 19c EE Extreme Perf Release 19.0.0.0.0 - Production
# Version 19.24.0.0.0
#
# SQL> select user from dual;
#
# USER
# ________
# ALICE
#
# SQL>

데이터베이스에서 로그아웃하고 자격 증명을 제거하려면:
# 특정 데이터베이스 인스턴스의 자격 증명 제거.
$ tsh db logout oracle
# 모든 데이터베이스 인스턴스의 자격 증명 제거.
$ tsh db logout

(선택 사항) 추가 호스트 이름 구성#

In some deployments the same logical database is reachable via multiple hostnames with different characteristics, for example:

replicated databases
hostnames that traverse different network paths

If this applies to your setup, list all hosts in order of preference to improve connection resiliency.
If a TCP dial error occurs for a host, the next host in the list is tried automatically. Non-network errors (e.g., certificate or authentication failures) are not retried and do not advance to the next host.
By default, hosts are attempted in the listed order. Retries cycle through the list and wrap to the start as needed (e.g., host1 → host2 → host3 → host1 → ...). To randomize the sequence per connection attempt, set shuffle_hostnames; the same cyclic pattern then applies to that randomized order.
retry_count controls the number of retries per host after the initial attempt on a network error. The default is 2, so there are 3 total attempts per host (1 initial + 2 retries) before moving to the next host in sequence.
This setup supports failover and basic load-balancing for new connections: enabling shuffle_hostnames spreads initial connection attempts across hosts (load-balancing), while retries automatically move to the next host if the current one is unreachable (failover).
- name: oracle
  protocol: oracle
  uri: host1:2484,host2:2484,host3:2484  # Multiple hosts; dials in sequence and wraps (host1 → host2 → host3 → host1 ...). Dialing sequence can be randomized with `shuffle_hostnames`.
  static_labels:
    env: dev
  oracle:
    # Randomize host order per connection attempt to spread load. Optional.
    shuffle_hostnames: true
    # Retries per host on network errors only; non-network errors stop (default: 2). Optional.
    retry_count: 5            


문제 해결#

Connection hangs or is refused#
A common issue when connecting to an Oracle database is a connection timeout or refusal. This typically indicates a networking problem where the Teleport Database Service cannot reach the Oracle database endpoint.
Verify that network routing and access controls, such as firewalls and VPC security groups, allow traffic to flow from the Database Service host to the database endpoint.
You can validate connectivity using a native Oracle client, which helps confirm whether the issue is with Teleport or the underlying network configuration. For example, using Oracle SQLcl:
# Example: Oracle SQLcl
sql -L myuser/mypassword@oracle-instance.example.com:2484

Network connectivity issues are often detected by automated health checks.
To check the health status of all registered databases:
# All databases
tctl db ls --format=json | jq -r '.[] | [.metadata.name, .status.target_health]'

An unhealthy database will have output similar to the following:
...
  "oracle",
  {
    "address": "11.22.33.44:2484",
    "protocol": "TCP",
    "status": "unhealthy",
    "transition_timestamp": "2025-09-25T09:47:39.435973Z",
    "transition_reason": "threshold_reached",
    "transition_error": "dial tcp 11.22.33.44:2484: i/o timeout",
    "message": "1 health check failed"
  }
...

TLS negotiation fails#
Properly configuring TLS on an Oracle database can be challenging. Different underlying issues can result in the same error message, such as the following from Teleport:
Original Error: *tls.permanentError remote error: tls: handshake failure

Or you might see the following in the Oracle logs:
ORA-00609: could not attach to incoming connection
ORA-28860: Fatal SSL error

To identify the root cause, follow the debugging steps in the sections below. The output of the following openssl command can help diagnose many common TLS issues. Capture the output and use it as you follow the debugging steps.
> openssl s_client -connect oracle.example.com:2484 -showcerts

Wrong server certificate#
Teleport rejects connections to databases with untrusted server certificates. If you are using Teleport to issue certificates, ensure that the server certificate was issued by the Teleport Database CA. An invalid server certificate will prevent Teleport from establishing a secure connection.
You can view the Teleport Database CA certificate with the following command:
tctl auth export --type=db | openssl x509 -issuer -noout
...
issuer=O=teleport.example.com, CN=teleport.example.com, serialNumber=200129862304303044762346177566738813560

Compare the issuer in the server certificate with the issuer of the Teleport Database CA certificate. The openssl s_client command from the previous section will show you the server certificate:
# openssl s_client output:
...
Server certificate
subject=CN=oracle.example.com
issuer=O=teleport.example.com, CN=teleport.example.com, serialNumber=200129862304303044762346177566738813560
...

You can also inspect the Oracle wallet directly using the orapki utility to verify the server certificate.
# Prompt for wallet password
orapki wallet display -complete -wallet /path/to/wallet

The "User Certificates" section of the output should contain the server's certificate. Its Issuer should match the Subject of the Teleport Database CA.
User Certificates:
Subject:        CN=oracle.example.com
Issuer:         SERIALNUMBER=200129862304303044762346177566738813560,CN=teleport.example.com,O=teleport.example.com
Serial Number:  ...

Wrong client certificate#
If the Oracle server rejects client certificates presented by the Teleport Database Service, you should verify that the Oracle database trusts the Teleport Database User CA.
You can view the Teleport Database User CA with this command:
tctl auth export --type=db-client | openssl x509 -issuer -noout
issuer=O=teleport.example.com, CN=teleport.example.com, serialNumber=183359545647055551607366887578713393931

Compare the Teleport Database User CA with the list of CAs trusted by the Oracle database. The openssl s_client command from earlier will show the list of CAs the Oracle database trusts:
# openssl s_client output:
...
---
Acceptable client certificate CA names
O=teleport.example.com, CN=teleport.example.com, serialNumber=183359545647055551607366887578713393931

Ensure that the Teleport Database User CA certificate has been added to the correct wallet and that the Oracle server configuration references this wallet.
You can also inspect the Oracle wallet directly using the orapki utility to verify that the Teleport Database User CA is trusted.
# Prompt for wallet password
orapki wallet display -complete -wallet /path/to/wallet

The "Trusted Certificates" section of the output should contain the Teleport Database User CA. Its Issuer should match the issuer of the Teleport Database User CA.
Trusted Certificates:
Subject:        SERIALNUMBER=183359545647055551607366887578713393931,CN=teleport.example.com,O=teleport.example.com
Issuer:         SERIALNUMBER=183359545647055551607366887578713393931,CN=teleport.example.com,O=teleport.example.com
Serial Number:  ...

Wrong TLS version#
Teleport rejects connections that use TLS 1.0 or 1.1 due to known weaknesses. Ensure that the SSL_VERSION parameter in your Oracle configuration is set to 1.2 or higher to enable TLS 1.2 or a newer version.
No common cipher suites#
Ensure that the SQLNET.CIPHER_SUITE parameter in your Oracle configuration contains modern TLS cipher suites that match the configured TLS version.
The following cipher suites are secure and widely supported across different Oracle versions.
For TLS 1.2:

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

For TLS 1.3:

TLS_AES_128_GCM_SHA256
TLS_AES_256_GCM_SHA384

Must be logged on to the server error#
The following error indicates that the login procedure has failed:
ORA-17430: Must be logged on to the server.

This is most commonly caused by the Oracle database enforcing native encryption or data-integrity checksums on a TCPS endpoint.
Teleport uses TLS for transport security, and does not support native Oracle encryption.
To disable the redundant encryption requirement for the TCPS endpoint, add the following line to your sqlnet.ora file:
SQLNET.IGNORE_ANO_ENCRYPTION_FOR_TCPS=TRUE
Make sure to use an up-to-date version of the Oracle database. In older versions, this setting may not disable data-integrity checksums, which will lead to continued failures.
Invalid username#
An incorrectly specified username will result in the following error:
ORA-01017: invalid username/password; logon denied

When using TLS-based authentication, Oracle maps the Common Name (CN) from the client certificate to an external user in the database. Verify the EXTERNAL_NAME for your user in the dba_users table. It should be in the format cn=<name>, where <name> matches the value of the --db-user flag used in the tsh db login command.
You can query the dba_users table to check the EXTERNAL_NAME of your users:
SQL> SELECT username, authentication_type, external_name
  2  FROM   dba_users
  3  WHERE  authentication_type = 'EXTERNAL'
  4  ORDER  BY 1;

USERNAME      AUTHENTICATION_TYPE    EXTERNAL_NAME
_____________ ______________________ ________________
ALICE         EXTERNAL               cn=alice


다음 단계#



Learn how to restrict access to certain users and databases.


View the High Availability
(HA) guide.


Take a look at the YAML configuration reference.


See the full CLI reference.



다음 문서를 참조하세요:

Oracle Audit Trail
sqlnet.ora 및 listener.ora 구성
Oracle Exadata
Oracle Real Application Clusters (RAC)